Single Signon

IBM i
7.2
Security
Single sign-on
IBM
Note
Before using this information and the product it supports, read the information in “Notices” on page
71.
This edition applies to IBM i 7.2 (product number 5770-SS1) and to all subsequent releases and modifications until
otherwise indicated in new editions. This version does not run on all reduced instruction set computer (RISC) models nor
does it run on CISC models.
This document may contain references to Licensed Internal Code. Licensed Internal Code is Machine Code and is
licensed to you under the terms of the IBM License Agreement for Machine Code.
© Copyright International Business Machines Corporation 2004, 2013.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents
Single sign-on....................................................................................................... 1
What's new for IBM i 7.2..............................................................................................................................1
PDF file for Single sign-on............................................................................................................................1
Concepts.......................................................................................................................................................2
Single sign-on overview..........................................................................................................................2
Authentication........................................................................................................................................ 3
Authorization.......................................................................................................................................... 3
Domains.................................................................................................................................................. 5
Identity mapping.................................................................................................................................... 6
IBM i enablement................................................................................................................................... 7
ISV enablement...................................................................................................................................... 8
Scenarios...................................................................................................................................................... 9
Scenario: Creating a single sign-on test environment...........................................................................9
Completing the planning work sheets............................................................................................12
Creating a basic single sign-on configuration for System A.......................................................... 15
Adding System A service principal to the Kerberos server............................................................17
Creating home directory for John Day on System A...................................................................... 18
Testing network authentication service configuration on System A............................................. 18
Creating an EIM identifier for John Day......................................................................................... 19
Testing EIM identity mappings....................................................................................................... 19
Configuring IBM i Access Client Solutions applications to use Kerberos authentication.............20
Verifying network authentication service and EIM configuration................................................. 20
(Optional) Postconfiguration considerations................................................................................. 21
Scenario: Enabling single sign-on for IBM i......................................................................................... 21
Completing the planning work sheets............................................................................................26
Creating a basic single sign-on configuration for System A.......................................................... 32
Configuring System B to participate in the EIM domain................................................................ 34
Adding both IBM i service principals to the Kerberos server........................................................ 36
Creating user profiles on System A and System B.........................................................................37
Creating home directories on System A and System B................................................................. 37
Testing network authentication service on System A and System B............................................ 37
Creating EIM identifiers for two administrators, John Day and Sharon Jones............................. 38
Creating identifier associations for John Day................................................................................ 38
Creating identifier associations for Sharon Jones......................................................................... 40
Creating default registry policy associations................................................................................. 41
Enabling registries to participate in lookup operations and to use policy associations............... 42
Testing EIM identity mappings....................................................................................................... 43
Configuring IBM i Access Client Solutions applications to use Kerberos authentication.............46
Verifying network authentication service and EIM configuration................................................. 46
(Optional) Postconfiguration considerations................................................................................. 47
Scenario: Enabling single sign-on for ISV applications.......................................................................47
Completing the planning prerequisite worksheet......................................................................... 49
Writing a new application or change an existing application........................................................ 49
Creating a single sign-on test environment................................................................................... 50
Testing your application..................................................................................................................50
Example: ISV code..........................................................................................................................50
Planning for single sign-on ....................................................................................................................... 57
Requirements for configuring a single sign-on environment.............................................................. 58
Single sign-on planning worksheets.................................................................................................... 59
Configuring single sign-on......................................................................................................................... 62
Managing single sign-on............................................................................................................................ 64
iii
Troubleshooting single sign-on................................................................................................................. 64
Related information................................................................................................................................... 68
Notices................................................................................................................71
Programming interface information.......................................................................................................... 72
Trademarks................................................................................................................................................ 72
Terms and conditions.................................................................................................................................73
iv
Single sign-on
If you are looking for a way to eliminate the number of passwords that your users must use and that your
administrators must manage, then implementing a single sign-on environment might be the answer you
need.
This information presents a single sign-on solution for IBM® i, which uses network authentication service
(IBM's implementation of the Kerberos V5 standard from MIT) paired with Enterprise Identity Mapping
(EIM). The single sign-on solution reduces the number of sign-ons that a user must perform, as well as
the number of passwords that a user requires to access multiple applications and servers.
Note: Read the “Code license and disclaimer information” on page 68 for important legal information.
What's new for IBM i 7.2

Read about new or significantly changed information for the single sign-on topic collection.
Miscellaneous updates have been made to this topic collection.
How to see what's new or changed

To help you see where technical changes have been made, the information center uses:
• The image to mark where new or changed information begins.
• The image to mark where new or changed information ends.
In PDF files, you might see revision bars (|) in the left margin of new and changed information.
To find other information about what's new or changed this release, see the Memo to users.
PDF file for Single sign-on

You can view and print a PDF file of this information.
To view or download the PDF version of this document, select Single sign-on.
You can view or download these related topics:
• Enterprise Identity Mapping (EIM). Enterprise Identity Mapping (EIM) is a mechanism for mapping
a person or entity (such as a service) to the appropriate user identities in various user registries
throughout the enterprise.
• Network authentication service. Network authentication service allows your system to participate in an
existing Kerberos network.
Saving PDF files

To save a PDF on your workstation for viewing or printing:
1. Right-click the PDF link in your browser.
2. Click the option that saves the PDF locally.
3. Navigate to the directory in which you want to save the PDF.
4. Click Save.
Downloading Adobe Reader

You need Adobe Reader installed on your system to view or print these PDFs. You can download a free
copy from the Adobe Web site (www.adobe.com/products/acrobat/readstep.html) .
© Copyright IBM Corp. 2004, 2013 1

Single sign-on concepts
Single sign-on uses multiple services and technologies to achieve a solution that offers simplified identity
and authorization management.
The following topics explain the benefits of single sign-on and how different services are used to create
this solution. Before you begin using single sign-on, you might find it helpful to review these concepts:
Single sign-on overview

A single sign-on solution is designed to alleviate the use of having multiple user names and passwords
across your enterprise. Implementing a single sign-on solution benefits user, administrators, and
application developers.
In traditional network environments, a user authenticates to a system or application by providing
user credentials defined on and by that system or application. Traditionally, both authentication and
authorization mechanisms use the same user registry when a user attempts to access a resource
managed by the system or application. In a single sign-on environment, authentication and authorization
mechanisms do not have to use the same user registry to enable users to resources managed by
the system or application. Single sign-on environments use network authentication service (Kerberos
authentication) as their authentication mechanism. In an single sign-on environment, the user registry
used for authentication does not have to be the registry that the system or application defines. In a
traditional network environment, this poses a problem for authorization.
In an single sign-on network environment, applications use Enterprise Identity Mapping (EIM) to solve
this problem. EIM is a mechanism for mapping or associating a person or entity to the appropriate user
identities in various registries throughout the enterprise. Application developers for IBM i use EIM to build
applications that use one user registry for authentication and another for authorization--without requiring
the user to provide another set of credentials. The benefits of a single sign-on environment are numerous,
and not just for users. Administrators and application developers can also benefit from the single sign-on
solution.
Benefits for users

The single sign-on solution reduces the number of sign-ons that a user must perform to access multiple
applications and servers. With single sign-on, authentication occurs only once when users sign into the
network. Using EIM reduces the need for users to keep track of and manage multiple user names and
passwords to access other systems in the network. After a user is authenticated to the network, the user
can access services and applications across the enterprise without the need for multiple passwords to
these different systems.
Benefits for administrators

For an administrator, single sign-on simplifies overall security management of an enterprise. Without
single sign-on, users might cache passwords to different systems, which can compromise the security of
the entire network. Administrators spend their time and money on solutions to diminish these security
risks. Single sign-on reduces the administrative overhead in managing authentication while helping to
keep the entire network secure. Additionally, single sign-on reduces the administrative costs of resetting
forgotten passwords. Administrators can set up a single sign-on environment where a user for a Microsoft
Windows operating system can sign-on once and have access to the entire network, thus minimizing
authentication and identification management.
Benefits for application developers

For developers of applications that must run in heterogeneous networks, the challenge is to create
multi-tiered applications where each tier is likely to be a different type of platform. By exploiting
EIM, application developers are free to write applications that use the most appropriate existing
user registry for authentication while using a different user registry for authorization. Not having to
2 IBM i: Single sign-on

implement application specific user registries, associated security semantics, and application level
security significantly lowers the cost of implementing multi-tiered, cross-platform applications.
Related concepts
Authentication
Authentication is part of a single sign-on solution because it identifies who a user is and then proves it,
typically based on a user name and password.
Authorization
Authorization is a process in which a user is granted access to a network or system resource.
Related information
Enterprise Identity Mapping
Authentication
The process of authentication is different from the process of authorization, in which an entity or a person
is granted or denied access to a network or system resource.
A single sign-on environment streamlines the process and management of authentication for users and
administrators. Because of the way single sign-on is implemented on your system, not only do users
need to supply fewer IDs and passwords but, if you choose to, they do not even need to have a IBM
i passwords. Administrators need to troubleshoot identity and password problems less often because
users need to know fewer identities and passwords to access the systems that they use.
Interfaces that are enabled for single sign-on require the use of Kerberos as the authentication method.
Network authentication service is the IBM i implementation of the Kerberos authentication function.
Network authentication service provides a distributed authentication mechanism through the use of a
Kerberos server, also called a key distribution center (KDC), which creates service tickets that are used to
authenticate the user (a principal in Kerberos terms) to some service on the network. The ticket provides
proof of the principal's identity to other services that the principal requests in the network.
Note: If you are an application developer, it is possible to make use of other types of authentication
methods as you enable your applications to work in a single sign-on environment. For example, you can
create applications that use an authentication method, such as digital certificates, in conjunction with EIM
APIs to enable your application to participate in a single sign-on environment.
Related concepts
Authorization
Related information
Network authentication service
Authorization
Most enterprises use a two-stage process to allow users to access network assets. The first stage
of this process is authentication. Authentication is a process in which a user identifies themselves to
the enterprise. Typically this requires the user to provide an identifier and a password to the security
component of the enterprise. The security component verifies the information that it receives. After a
successful authentication, the user is issued a process they can use, a credential, or a ticket to use to
demonstrate that they have already authenticated to the enterprise. An example of a user authentication
is the ID and password challenge on an IBM i Access Client Solutions 5250 emulator connection. After
Single sign-on 3
successful authentication, the user is assigned a job that runs under their user ID. The second stage is
authorization. It is important to know the distinction between authentication and authorization.
Authorization is the process of determining if an entity or person has the authority to access an asset
within an enterprise. Authorization checks are done after a user has authenticated to the enterprise,
because authorization requires that the enterprise knows who is trying to gain access. Authorization
checking is mandatory and occurs as part of the system. Users are typically unaware that authorization
checks occur unless their access is denied. An example of authorization occurs when a user uses
the command CRTSRCPF QGPL/MYFILE. The system performs authorization checks on the command
CRTSRCPF and the library QGPL. If the user does not have the authority to access the command and the
library, the user's request fails.
An enterprise that has implemented the IBM i single sign-on solution uses Enterprise Identity Mapping
(EIM) to manage user access to enterprise assets. While EIM does not perform authorization checks, the
identity mapping establishes the local identities for users that have successfully authenticated into the
enterprise. The source (or user) receives access and privileges on the target system through the local ID.
For example, assume you have the following simple enterprise environment:
Employee Source Users Target users Employee System A User Comments

Name (EIM (EIM Source) for System A Responsibility
Identity) (EIM Target)
Susan Doe SusanD SecOfficer IT Security All special authority. Has access
Officer to all files and information.
Fred Ray FredR PrimeAcnt Lead No special authority. Has access
Accountant to all payroll information.
Nancy Me NancyM PrimePGM IT Application No special authority. Has access
Team Leader to all company application
source files.
Brian Fa BrianF GenAcnt1 Accountant No special authority. Has access
to some payroll information.
Tracy So TracyS ITPgm2 IT Programmer No special authority. Has access
to some company application
source files.
Daryl La DarylL ITPgm3 IT Programmer No special authority. Has access
to some company application
source files.
Sherry Te SherryT PrimeMKT Marketing No special authority. Has access
Representative to all marketing data.
It is important that all of the associations between users and resources are set up correctly. If the
associations are incorrect, users will have access to data outside the scope of their responsibilities, which
is a security concern for most enterprises. System administrators need to be very careful when creating
the EIM mappings and ensure that they map users to the correct local registry IDs. For example if you
mapped the IT Programmer, Daryl La, to the SecOfficer ID instead of Susan Doe, you could compromise
the security of the system. This reinforces the fact that security administrators must still take care in
securing the target systems within the enterprise.
Related concepts
Authentication

Related information
Domains
EIM and Windows domains are used to implement a single sign-on environment.
Although both the EIM domain and Windows domain contain the word domain, they have very different
definitions. Use the following descriptions to understand the differences between these two types of
domains.
EIM domain
An EIM domain is a collection of data, which includes the EIM identifiers, EIM associations, and EIM
user registry definitions that are defined in that domain. This data is stored in a Lightweight Directory
Access Protocol (LDAP) server, such as the IBM Tivoli® Directory Server for IBM i, which can run on any
system in the network, defined in that domain. Administrators can configure systems (EIM clients),
such as IBM i, to participate in the domain so that systems and applications can use domain data for
EIM lookup operations and identity mapping.
Windows domain
In the context of single sign-on, a Windows domain is a Windows network that contains several
systems operating as clients and servers and a variety of services and applications used by the
systems. The following are some of the components pertinent to single sign-on that you might find
within a Windows domain:
Realm
A realm is a collection of machines and services. The main purpose of a realm is to authenticate
clients and services. Each realm uses a single Kerberos server to manage the principals for that
particular realm.
Kerberos server
A Kerberos server, also known as a key distribution center (KDC), is a network service that
resides on the Windows server and provides tickets and temporary session keys for network
authentication service. The Kerberos server maintains a database of principals (users and
services) and their associated secret keys. It is composed of the authentication server and the
ticket granting server. A Kerberos server uses Microsoft Windows Active Directory to store and
manage the information in a Kerberos user registry.
Microsoft Windows Active Directory
Microsoft Windows Active Directory is an LDAP server that resides on the Windows server along
with the Kerberos server. The Active Directory is used to store and manage the information in a
Kerberos user registry. Microsoft Windows Active Directory uses Kerberos authentication as its
default security mechanism. Therefore, if you are using Microsoft Active Directory to manage your
users, you are already using Kerberos technology.
Related concepts
Identity mapping
Identity mapping is the process of using defined relationships between user identities in an enterprise
such that applications and operating systems can map from one user identity to another, related user
identity.
Related information
Enterprise Identity Mapping Concepts
Single sign-on 5
Identity mapping
Identity mapping is the process of using defined relationships between user identities in an enterprise
such that applications and operating systems can map from one user identity to another, related user
identity.
The ability to map between identities is essential to single sign-on enablement, as it allows you to
separate the process of authentication from that of authorization. Identity mapping allows a user to log on
to a system and be authenticated based on the credentials of one user identity and then be able to access
a subsequent system or resource without having to supply new credentials. Instead, the authenticated
identity is mapped to the appropriate identity for the requested system or resource. Not only does this
make life easier for the user, who need not supply a second credential for logging on to the second
system, but the authorizations he has for the second system are handled by the appropriate identity.
To implement single sign-on, you need to create certain EIM data within the EIM domain to define the
relationships needed to appropriately map identities within your single sign-on environment. Doing so
ensures that EIM can use that data to perform mapping lookup operations for single sign-on. You use
EIM to create associations to define the relationships between user identities in your enterprise. You can
create both identifier associations and policy associations to define these relationships depending on how
you want identity mapping to work.
Identifier associations
Identifier associations allow you to define a one-to-one relationship between user identities through an
EIM identifier defined for an individual. Identifier associations allow you to specifically control identity
mapping for user identities and are especially useful when individuals have user identities with special
authorities and other privileges. These associations dictate how the user identities are mapped from
one to another. In a typical identity mapping situation, you create source associations for authenticating
user identities and target associations to map the authenticating user identity to the appropriate user
identities for authorized access to other systems and resources. For example, you might typically create
the following identifier associations between an EIM identifier and corresponding user identities for a
user:
• A source association for the user's Kerberos principal, which is the identity with which the user logs
into, and is authenticated to, the network.
• Target associations for each user identity in the various user registries that the user accesses, such as
IBM i user profiles.
The following example illustrates how the identity mapping process works for identifier associations.
The security administrator at Myco, Inc creates an EIM identifier (John Day) for an employee. This
EIM identifier uniquely identifies John Day in the enterprise. The administrator then creates identifier
associations between the John Day identifier and two user identities that he routinely uses in the
enterprise. These associations define how the user identities are mapped. The administrator creates a
source association for the Windows identity, which is a Kerberos principal, and a target association for an
IBM i user profile. These associations enable his Windows identity to be mapped to his IBM i user profile.
John Day uses the appropriate user name and password to log on to his Windows workstation each
morning. After he has logged on, he starts IBM i Access Client Solutions to use his Windows workstation
to access the IBM i system using IBM i Access Client Solutions applications. Because single sign-on is
enabled, the identity mapping process uses his authenticated Windows identity to find the associated
IBM i user profile and transparently authenticates and authorizes him to the IBM i system.
In previous releases of IBM i single sign-on only supported mapping to one local user identity in
Enterprise Identity Mapping (EIM) per system. Currently, single sign-on supports selecting from multiple
local user identity mappings for the same system, using the IP address of the target system to select the
correct local user identity mapping on that system.

Policy associations
Policy associations allow you to define a many-to-one relationship between a group of user identities in
one or more user registries and a specific individual target user identity in another user registry. Typically,
you use policy associations to map from a group of users who require the same level of authority for an
application to a single user identity with the appropriate authority.
The following example illustrates how identity mapping works when you define policy associations.
A number of workers in the Order Receiving Department of Myco, Inc. all need the same type of
authorization to access a Web-based application that runs on the Windows server. These users currently
have user identities for this purpose in a single user registry named Order_app. The administrator creates
a default registry policy association to map all the users in the Order_app user registry to a single
Windows identity. This Windows identity, SYSUSER, provides the minimum authority needed for this group
of users. Performing this single configuration step allows the administrator to ensure that all users of the
Web-based application have the access they need with the proper level of authorization that they need.
However, the administrator also benefits because it eliminates the need to create and maintain individual
Windows identities for each user.
Related concepts
Domains
EIM and Windows domains are used to implement a single sign-on environment.
Related information
EIM identifiers
EIM registry definitions
EIM associations
EIM mapping lookup operations
EIM domain
IBM i enablement
The IBM i implementation of Enterprise Identity Mapping (EIM) and Kerberos (referred to as network
authentication services) provides a true multi-tier single sign-on environment.
The network authentication service is IBM's implementation of Kerberos and the Generic Security Service
(GSS) APIs. You can use EIM to define associations that will provide a mapping between a Kerberos
principal and an IBM i user profile. You can then use this association to determine which EIM identifier
corresponds to a local IBM i user profile or Kerberos principal. This is one of the benefits of enabling
single sign-on in IBM i on the server.
IBM i enablement of single sign-on

To enable a single sign-on environment, IBM exploits two technologies that work together: EIM and
network authentication service, which is IBM's implementation of Kerberos and the GSS APIs. By
configuring these two technologies, an administrator can enable a single sign-on environment. Windows,
AIX®, and z/OS® use Kerberos protocol to authenticate users to the network. Kerberos involves the use
of a network-based, secure, key distribution center which authenticates principals (Kerberos users) to
the network. The fact that a user has authenticated to the KDC is represented by a Kerberos ticket. A
ticket can be passed from a user to a service that accepts tickets. The service accepting a ticket uses it
to determine who the user claims to be (within the Kerberos user registry and realm) and that they are in
fact who they claim to be.
While network authentication service allows a server to participate in a Kerberos realm, EIM provides a
mechanism for associating these Kerberos principals to a single EIM identifier that represents that user
within the entire enterprise. Other user identities, such as an IBM i user name, can also be associated with
this EIM identifier. Based on these associations, EIM provides a mechanism for IBM i and applications to
determine which IBM i user profile represents the person or entity represented by the Kerberos principal.
You can think of the information in EIM as a tree with an EIM identifier as the root, and the list of user
identities associated with the EIM identifier as the branches.
Single sign-on 7
Enabling single sign-on for your server simplifies the task of managing IBM i user profiles and reduces
the number of sign-ons that a user must perform to access multiple IBM i applications and servers.
Additionally, it reduces the amount of time that is required for password management by each user. Single
sign-on allows each user to remember and use fewer passwords to access applications and servers,
thereby simplifying their IBM i experience.
IBM i client and server applications currently enabled for single sign-on
• IBM i Host Servers is currently used by IBM i Access Client Solutions.
• Telnet server: currently used by PC5250 and IBM WebSphere® Host On-Demand Version 8: Web
Express Logon feature.
• Telnet client
• Open DataBase Connectivity (ODBC): allows single sign-on access to IBM i databases through ODBC.
• Java™ Database Connectivity (JDBC): allows single sign-on access to IBM i databases through ODBC.
• Distributed Relational Database Architecture™ (DRDA): allows single sign-on access to IBM i databases
through ODBC.
• QFileSrv.400
• FTP client and FTP server
ISV enablement
An independent software vendor (ISV) can create applications and programs that can participate in a
single sign-on environment.
As an ISV you know that many of your customers are implementing single sign-on environments to
take advantage of the cost and time benefits that single sign-on provides. You want to ensure that you
design your application products to participate in single sign-on environments so that you can continue to
provide the solutions that your customers want and need.
To enable your applications to participate in an IBM i single sign-on environment, you need to perform the
following tasks:
Enable your IBM i server applications for EIM
One of the foundations of a single sign-on environment is Enterprise Identity Mapping (EIM). EIM is a
mechanism for mapping or associating a person or entity to the appropriate user identities in various
registries throughout the enterprise. Application developers for IBM i use EIM to build applications
that use one user registry for authentication and another for authorization--without requiring the user
to provide another set of credentials. EIM provides APIs for creating and managing these identity
mapping relationships, as well as APIs that applications use to query this information. You can write
applications that use EIM APIs to perform lookup operations for user identities within an enterprise.
Enable your IBM i server and client applications to use a common authentication mechanism
While you are free to choose any common authentication mechanism you want for your application's
single sign-on environment, the IBM i single sign-on environment is based on the network
authentication service (Kerberos) which provides an integrated single sign-on environment with
Windows domains. If you want your applications to participate with the same secure, integrated single
sign-on environment as IBM i, should choose network authentication service as the authentication
mechanism for your applications. The following are examples of the different authentication methods
you can choose for your applications:
Network authentication service
Use the Scenario: Enable single sign-on for ISV applications to learn how to use EIM application
programming interfaces (APIs) in conjunction with network authentication service to create
applications that can fully participate in a single sign-on environment. This scenario includes some
ISV code examples, including pseudocode, for example pseudocode and snippets that you can
use to help complete your program.

Digital certificates
It is possible to develop applications for a single sign-on environment that use digital certificates
as the authentication method. To insert the necessary code into your program for authenticating
with digital certificates, you must use the Digital Certificate Management APIs.
Lightweight Directory Access Protocol (LDAP)
It is possible to develop applications for a single sign-on environment that use the directory server
as the authentication method. To insert the necessary code into your program for authenticating
with the directory server, you must use the Lightweight Directory Access Protocol (LDAP) APIs.
Related information
EIM APIs
Scenarios: Single sign-on

Theses scenarios provide real world examples for planning, configuring, and using single sign-on in an
enterprises.
Although all of these scenarios provide models for network administrators, there is also a scenario
for application developers that demonstrates the tasks that a developer needs to complete to create
applications that can participate in a single sign-on environment.
Scenario: Creating a single sign-on test environment

In this scenario, you want to configure network authentication service and EIM to create a basic single
sign-on test environment. Use this scenario to gain a basic understanding of what configuring a single
sign-on environment involves on a small scale before implementing single sign-on across an entire
enterprise.
Situation
You, John Day, are a network administrator for a large wholesale company. Currently you spend much
of your time troubleshooting password and user identity problems, such as forgotten passwords. Your
network is comprised of several IBM i models and a Windows server, where your users are registered
in Microsoft Windows Active Directory. Based on your research, you know that Microsoft Active Directory
uses the Kerberos protocol to authenticate Windows users. You also know that the IBM i platform
provides a single sign-on solution based on an implementation of Kerberos authentication, called network
authentication service, in conjunction with EIM.
You are excited about the benefits of using single sign-on. However, you want to thoroughly understand
single sign-on configuration and usage before you begin using it across your entire enterprise.
Consequently, you decide to configure a test environment first.
After considering the various groups in your company, you decide to create the test environment for the
Order Receiving department. The employees in the Order Receiving department use multiple applications
on one IBM i model to handle incoming customer orders. Consequently, the Order Receiving department
provides an excellent opportunity for you to create a single sign-on test environment that you can use to
better understand how single sign-on works and how to plan a single sign-on implementation across your
enterprise.
Scenario advantages
• Allows you to see some of the benefits of single sign-on on a small scale to better understand how you
can take full advantage of it before you create a large-scale, single sign-on environment.
• Provides you with a better understanding of the planning process you need to use to successfully and to
more quickly implement single sign-on across your entire enterprise.
• Minimizes the learning curve of implementing single sign-on across your enterprise.
Single sign-on 9
Objectives
As the network administrator at MyCo, Inc., you want to create a small single sign-on environment for
testing that includes a small number of users and a single IBM i model. You want to perform thorough
testing to ensure that user identities are correctly mapped within your test environment. Based on this
configuration, you eventually want to expand the test environment to include the other systems and users
in your enterprise.
The objectives of this scenario are as follows:
• The IBM i model, known as System A, must be able to use Kerberos within the MYCO.COM realm to
authenticate the users and services that are participating in this single sign-on test environment. To
enable the system to use Kerberos, System A must be configured for network authentication service.
• The directory server on System A must function as the domain controller for the new EIM domain.
Note: Refer to “Domains” on page 5 to learn how an EIM domain and a Windows domain both fit into
the single sign-on environment.
• One user profile on System A and one Kerberos principal must each be mapped to a single EIM
identifier.
• A Kerberos service principal must be used to authenticate the user to the IBM i Access Client Solutions
applications.
Details
The following figure illustrates the network environment for this scenario.
The figure illustrates the following points relevant to this scenario.

EIM domain data defined for the enterprise
• An EIM registry definition for System A called SYSTEMA.MYCO.COM.
• An EIM registry definition for the Kerberos registry called MYCO.COM.

• An EIM identifier called John Day. This identifier uniquely identifies John Day, the administrator for
MyCo.
• A source association for the jday Kerberos principal on the Windows server.
• A target association for the JOHND user profile on System A.
Windows server
• Acts as the Kerberos server (kdc1.myco.com), also known as a key distribution center (KDC), for the
network.
• The default realm for the Kerberos server is MYCO.COM.
• A Kerberos principal of jday is registered with the Kerberos server on the Windows server. This principal
will be used to create a source association to the EIM identifier, John Day.
System A
• Runs IBM i 5.4, or later, with the following options and licensed programs installed:
– IBM i Host Servers (5770-SS1 Option 12)
– Qshell Interpreter (5770-SS1 Option 30)
• The IBMTivoli Directory Server for IBM i (LDAP) on System A will be configured to be the EIM domain
controller for the new EIM domain, MyCoEimDomain.
• System A participates in the EIM domain, MyCoEimDomain.
• The principal name for System A is krbsvr400/[email protected].
• The user profile of JOHND exists on System A. You will create a target association between this user
profile and the EIM identifier, John Day.
• The home directory for the IBM i user profile, JOHND, (/home/JOHND) is defined on System A.
Client PC used for single sign-on administration
• Runs Microsoft Windows operating system.
• Serves as the primary logon system for administrator John Day.
• Configured to be part of the MYCO.COM realm (Windows domain).
Prerequisites and assumptions

Successful implementation of this scenario requires that the following assumptions and prerequisites are
met:
1. All system requirements, including software and operating system installation, have been verified.
To verify that the licensed programs have been installed, complete the following:
a. From IBM Navigator for i, expand IBM i Management > Configuration and Service > Software.
b. Click Installed Products.
c. Ensure that all the necessary licensed programs are installed.
2. All necessary hardware planning and setup is complete.
3. TCP/IP and basic system security are configured and tested on each system.
4. The directory server and EIM should not be previously configured on System A.
Note: Instructions in this scenario are based on the assumption that the directory server has not been
previously configured on System A. However, if you already configured the directory server, you can
still use these instructions with only slight differences. These differences are noted in the appropriate
places within the configuration steps.
5. A single DNS server is used for host name resolution for the network. Host tables are not used for host
name resolution.
Note: The use of host tables with Kerberos authentication might result in name resolution errors or
other problems.
Single sign-on 11
Configuration steps
Note: You need to thoroughly understand the concepts related to single sign-on which include network
authentication service and Enterprise Identity Mapping (EIM) concepts, before you implement this
scenario. If you are ready to continue with this scenario complete the following steps:
Related tasks
Testing your application
You have completed the development of both client and server specific updates to your Calendar
application, enabling it for an IBM i single sign-on environment. You are now ready to test it.
Configuring single sign-on
To configure a single sign-on environment you must use a compatible authentication method as your
authentication method and Enterprise Identity Mapping (EIM) to create and manage your user profiles
and identity mappings.
Related information
Host name resolution considerations
Enterprise Identity Mapping (EIM)
Completing the planning work sheets

The following planning work sheets are tailored to fit this scenario based on the general single sign-on
planning worksheets.
These planning work sheets demonstrate the information that you need to gather and the decisions
you need to make to prepare the single sign-on implementation described by this scenario. To ensure a
successful implementation, you must be able to answer Yes to all prerequisite items in the work sheet
and you should gather all the information necessary to complete the work sheets before you perform any
configuration tasks.
Note: You need to thoroughly understand the concepts related to single sign-on which include network
scenario.
Table 1. Single sign-on prerequisite work sheet

Prerequisite work sheet Answers
Is your system running IBM i 5.4 or later? Yes
Are the following options and licensed programs installed on Yes
System A?
• IBM i Host Servers (5770-SS1 Option 12)
• Qshell Interpreter (5770-SS1 Option 30)
Have you installed an application that is enabled for single sign- Yes
on on each of the PCs that will participate in the single sign-on
environment?
Note: For this scenario, all of the participating PCs have IBM i
Access Client Solutions (5733-XJ1) installed. See IBM i Access
Client Solutions: Getting Started
Do you, the administrator, have *SECADM, *ALLOBJ, and Yes

*IOSYSCFG special authorities?

Table 1. Single sign-on prerequisite work sheet (continued)
Do you have one of the following systems acting as the Yes, Windows server
Kerberos server (also known as the KDC)? If yes, specify which
system.
1. Windows server
2. IBM i PASE 5.4, or later
3. AIX server
4. z/OS
Are all your PCs in your network configured in a Windows Yes

domain?
Have you applied the latest program temporary fixes (PTFs)? Yes
Is the IBM i model time within 5 minutes of the system time on Yes
the Kerberos server? If not see Synchronizing system times.
Are you running IBM i PASE for the Kerberos server? You must have IBM Network
Authentication Enablement for i(5770-
NAE) installed.
You need this information to configure EIM and network authentication service to create a single sign-on
test environment.
Table 2. Single sign-on configuration planning work sheet for System A

Configuration planning work sheet for System A Answers
Use the following information to complete the EIM Configuration wizard. The information in this work
sheet correlates with the information you need to supply for each page in the wizard:
How do you want to configure EIM for your system? Create and join a new domain
• Join an existing domain
• Create and join a new domain
Where do you want to configure your EIM domain? On the local directory server
Note: This will configure the directory
server on the same system on which you
are currently configuring EIM.
Do you want to configure network authentication service? Yes

Note: You must configure network authentication service to
configure single sign-on.
The Network Authentication Service wizard opens from the EIM Configuration wizard. Use the following
information to complete the Network Authentication Service wizard:
Note: You can launch the Network Authentication Service wizard independently of the EIM Configuration
wizard.
What is the name of the Kerberos default realm to which MYCO.COM

your IBM i model will belong?
Note: A Windows domain is similar to a Kerberos realm.
Are you using Microsoft Active Directory? Yes
Single sign-on 13
Table 2. Single sign-on configuration planning work sheet for System A (continued)
What is the Kerberos server, also known as a key KDC: kdc1.myco.com
distribution center (KDC), for this Kerberos default realm? Port: 88
What is the port on which the Kerberos server listens?
Note: This is the default port for the
Kerberos server.
Do you want to configure a password server for this default Yes

realm? If yes, answer the following questions:
Password server: kdc1.myco.com
What is name of the password server for this Kerberos Port: 464
server?
What is the port on which the password server listens? Note: This is the default port for the
password server.
For which services do you want to create keytab entries? IBM i Kerberos Authentication
• IBM i Kerberos Authentication
• LDAP
• IBM HTTP Server for i
• IBM i NetServer
• IBM i Network File System (NFS) Server
What is the password for your service principal or systema123

principals?
Note: Any and all passwords specified in
this scenario are for example purposes
only. To prevent a compromise to your
system or network security, you should
never use these passwords as part of your
own configuration.
Do you want to create a batch file to automate adding the Yes

service principals for System A to the Kerberos registry?
Do you want to include passwords with the IBM i service Yes
principals in the batch file?
As you exit the Network Authentication Service wizard, you will return to the EIM Configuration wizard.
Use the following information to complete the EIM Configuration wizard:
Specify user information that the wizard should use when Port: 389
configuring the directory server. This is the connection Distinguished name:
user. You must specify the port number, administrator cn=administrator
distinguished name, and a password for the administrator. Password: mycopwd
Note: Specify the LDAP administrator's distinguished name
(DN) and password to ensure the wizard has enough
authority to administer the EIM domain and the objects in
it.
own configuration.
What is the name of the EIM domain that you want to MyCoEimDomain
create?
Do you want to specify a parent DN for the EIM domain? No

Which user registries do you want to add to the EIM Local IBM i--SYSTEMA.MYCO.COM
domain? Kerberos--MYCO.COM
Note: The Kerberos principals stored

on the Windows server are not case
sensitive; therefore you should not
select Kerberos user identities are case
sensitive.
Which EIM user do you want System A to use when User type: Distinguished name and
performing EIM operations? This is the system user. password
Note: If you have not configured the directory server before User: cn=administrator
configuring single sign-on, the only distinguished name Password: mycopwd
(DN) you can provide for the system user is the LDAP
administrator's DN and password.
own configuration.
After you complete the EIM Configuration wizard, use the following information to complete the
remaining steps required for configuring single sign-on:
What is the IBM i user profile name for the user? JOHND
What is the name of the EIM identifier that you want to John Day
create?
What kinds of associations do you want to create? Source association: Kerberos principal
jday
Target association: IBM i user profile
JOHND
What is the name of the user registry that contains the MYCO.COM
Kerberos principal for which you are creating the source
association?
What is the name of the user registry that contains the SYSTEMA.MYCO.COM
IBM i user profile for which you are creating the target
association?
What information do you need to supply to test EIM identity Source registry: MYCO.COM
mapping? Source user: jday
Target registry: SYSTEMA.MYCO.COM
Related information
Creating a basic single sign-on configuration for System A

The EIM Configuration wizard helps you create a basic EIM configuration and also opens the Network
Authentication Service wizard to allow you to create a basic network authentication service configuration.
Note: Instructions in this scenario are based on the assumption that the IBM Tivoli Directory Server for
IBM i has not been previously configured on System A. However, if you already configured the directory
Single sign-on 15
server, you can still use these instructions with only slight differences. These differences are noted in the
appropriate places within the configuration steps.
When you have finished this step, you will have completed the following tasks:
• Created a new EIM domain
• Configured the directory server on System A to be the EIM domain controller
• Configured network authentication service
• Created EIM registry definitions for the System A IBM i registry and the Kerberos registry in the newly
created EIM domain
• Configured System A to participate in the EIM domain
1. In IBM Navigator for i, expand IBM i Management > Security > All Tasks > Enterprise Identity
Mapping > Configuration.
2. Click Configure to start the EIM Configuration wizard.
3. On the Welcome page, select Create and join a new domain. Click Next.
4. On the Specify EIM Domain Location page, select On the local Directory server. Click Next and the
Network Authentication Service wizard is displayed.
Note: The Network Authentication Service wizard only displays when the system determines that
you need to enter additional information to configure network authentication service for the single
sign-on implementation.
5. Complete these tasks to configure network authentication service:
a) On the Configure Network Authentication Service page, select Yes.
Note: This launches the Network Authentication Service wizard. With this wizard, you can
configure several IBM i interfaces and services to participate in a Kerberos realm.
b) On the Specify Realm Information page, enter MYCO.COM in the Default realm field and select
Microsoft Active Directory is used for Kerberos authentication. Click Next.
c) On the Specify KDC Information page, enter kdc1.myco.com in the KDC field and enter 88 in
the Port field. Click Next.
d) On the Specify Password Server Information page, select Yes. Enter kdc1.myco.com in the
Password server field and 464 in the Port field. Click Next.
e) On the Select Keytab Entries page, select IBM i Kerberos Authentication. Click Next.
f) On the Create IBM i Keytab Entry page, enter and confirm a password, and click Next. For
example, systema123. This password will be used when System A is added to the Kerberos
server.
Note: Any and all passwords specified in this scenario are for example purposes only. To prevent a
compromise to your system or network security, you should never use these passwords as part of
your own configuration.
g) Optional: On the Create Batch File page, select Yes, specify the following information, and click
Next:
• Batch file: Add the text systema to the end of the default batch file name. For example, /
QIBM/UserData/OS400/iSeriesNavigator/config/NASConfig_systema.bat.
• Select Include password. This ensures that all passwords associated with the IBM i service
principal are included in the batch file. It is important to note that passwords are displayed
in clear text and can be read by anyone with read access to the batch file. Therefore, it is
recommended that you delete the batch file from the Kerberos server and from the IBM i
immediately after use.
Note: If you do not include the password, you will be prompted for the password when the batch
file is run.

h) On the Summary page, review the network authentication service configuration details and click
Finish to complete the Network Authentication Service wizard and return to the EIM Configuration
wizard.
6. On the Configure Directory Server page, enter the following information, and click Next:
Note: If you configured the directory server before you started this scenario, you will see the Specify
User for Connection page instead of the Configure Directory Server page. In that case, you must
specify the distinguished name and password for the LDAP administrator.
• Port: 389
• Distinguished name: cn=administrator
• Password: mycopwd
7. On the Specify Domain page, enter the name of the domain in the Domain field, and click Next. For
example, MyCoEimDomain.
8. On the Specify Parent DN for Domain page, select No, and click Next.
Note: If the directory server is active, a message is displayed that indicates you need to end and
restart the directory server for the changes to take effect. Click Yes to restart the directory server.
9. On the Registry Information page, select Local IBM i and Kerberos, and click Next. Write down the
registry names. You will need these registry names when you create associations to EIM identifiers.
Note:
• Registry names must be unique to the domain.
• You can enter a specific registry definition name for the user registry if you want to use a specific
registry definition naming plan. However, for this scenario you can accept the default values.
10. On the Specify EIM System User page, select the user the operating system uses when performing
EIM operations on behalf of operating system functions, and click Next.
Note: Because you did not configure the directory server prior to performing the steps in this
scenario, the only distinguished name (DN) that you can choose is the LDAP administrator's DN.
• User type: Distinguished name and password
11. On the Summary page, confirm the EIM configuration information. Click Finish.
Now that you have completed a basic EIM and network authentication service configuration on System A,
you can add the service principal for System A to the Kerberos server.
Adding System A service principal to the Kerberos server

You can use one of two methods to add the necessary IBM i service principal to the Kerberos server.
You can manually add the service principal or, as this scenario illustrates, you can use a batch file to add
it. You created this batch file in Step 2. To use this file, you can use the IFS download function in IBM
Navigator for i to copy the file to the Kerberos server and run it.
Follow these steps to use the batch file to add principals to the Kerberos server:
Download the batch file created by the wizard to your Kerberos server.
As the administrator on your Windows server do the following:
Single sign-on 17
a) In IBM Navigator for i on System A, expand IBM i Management > File Systems > Integrated File
System > Root > QIBM > UserData > OS400 > iSeriesNavigator > config
b) Right-click NASConfig_systema.bat and select Download.
c) Click the Download button on the Confirm Download page.
d) Save the file, this will put it in your browser's download location. Refer to your browser's
documentation for how to customize the download folder location. Usually this is the Downloads
folder.
Note: It is recommended that you now delete the NASConfig_systema.bat file from System A.
Run the batch file on kdc1.myco.com
1. On your Windows server, open the directory where you downloaded the batch file.
2. Find the NASConfig_systema.bat file and double-click the file to run it.
3. After the file runs, verify that the IBM i principal has been added to the Kerberos server by completing
the following:
a. On your Windows server, expand Administrative Tools > Active Directory Users and Computers.
b. Verify the IBM i model has a user account by selecting the appropriate Windows domain and
clicking Users.
Note: This Windows domain should be the same as the default realm name that you specified in the
network authentication service configuration.
c. In the list of users that is displayed, find systema_1_krbsvr400. This is the user account generated
for the IBM i principal name.
d. (Optional) Access the properties on your Active Directory user. From the Delegation tab, select
Trust this user for delegation to any service (Kerberos only).
Note: This optional step enables your system to delegate, or forward, a user's credentials to other
systems. As a result, the IBM i service principal can access services on multiple systems on behalf
of the user. This is useful in a multi-tier network.
Now that you have added the System A service principal to the Kerberos server, you can create a home
directory for John Day.
Creating home directory for John Day on System A

You need to create a directory in the /home directory to store your Kerberos credentials cache.
To create a home directory, complete the following:
On a command line, enter: CRTDIR '/home/user profile' where user profile is your IBM i user
profile name. For example: CRTDIR '/home/JOHND'.
Now that you have created the home directory, you can verify that network authentication service is
configured correctly.
Testing network authentication service configuration on System A

Now that you have completed the network authentication service configuration tasks for System A, you
need to test that your configuration works correctly. You can do this by requesting a ticket granting ticket
for the System A principal name
To test the network authentication service configuration, follow these steps:
Note: Ensure that you have created a home directory for your IBM i user profile before performing this
procedure.
1. On a command line, enter QSH to start the Qshell Interpreter.
2. Enter keytab list to display a list of principals registered in the keytab file. In this scenario,
krbsvr400/[email protected] should display as the principal name for System A.

3. Enter kinit -k krbsvr400/[email protected]. If this is successful, then the kinit
command is displayed without errors.
4. Enter klist to verify that the default principal is krbsvr400/[email protected].
Now that you have tested the network authentication service configuration, you can create an EIM
identifier for John Day.
Creating an EIM identifier for John Day

Now that you have performed the initial steps to create a basic single sign-on configuration, you can begin
to add information to this configuration to complete your single sign-on test environment.
You need to create the EIM identifier that you specified in the planning work sheet. In this scenario, this
EIM identifier is a name that uniquely identifies you, John Day, in your enterprise.
To create an EIM identifier, follow these steps:
Mapping.
2. Click Domain Management.
3. Right-click MyCoEimDomain and select Open.
Note: You might be prompted to connect to the domain controller. In that case, the Connect to EIM
Domain Controller dialog box is displayed. You must connect to the domain before you can perform
actions in it. To connect to the domain controller, provide the following information and click OK:
• User type: Distinguished name
4. Right-click Identifiers and select New Identifier.
5. On the New EIM Identifier dialog box, enter a name for the new identifier in the Identifier field, and
click OK. For example, John Day.
Now that you have created your identifier, you can add associations to the identifier to define the
relationship between the identifier and the corresponding Kerberos principal and IBM i user profile.
Testing EIM identity mappings

You need to verify that EIM mapping lookup operations return the correct results based on the configured
associations.
To test that EIM mapping operations work correctly, follow these steps:
Mapping.
3. Right-click MyCoEimDomain and select Test a mapping.
Single sign-on 19
4. In the Test a mapping dialog box, specify or Browse to select the following information:
• Source registry: MYCO.COM
• Source user: jday
• Target registry: SYSTEMA.MYCO.COM
Note: Click ? for help, if necessary, for more details about what information is needed for each field in
the dialog box.
Click Test, and click Close.
If your EIM mappings are correctly configured, the following results are displayed in the Mapping found
portion of the page:
For these fields See these results

Target user JOHND
Origin EIM Identifier: John Day
If you receive messages or errors that indicate problems with your mappings or with communications, see
EIM troubleshooting to help you find solutions to these problems.
Now that you have tested the EIM identify mappings, you can configure IBM i Access Client Solutions
applications to use Kerberos authentication.
Configuring IBM i Access Client Solutions applications to use Kerberos

authentication
You must use Kerberos to authenticate before you can use IBM i Access Client Solutions applications to
access your system. Therefore, from your PC, you need to configure IBM i Access Client Solutions to use
Kerberos authentication.
To configure IBM i Access Client Solutions applications to use Kerberos authentication, complete the
following steps:
Note: Each of your users needs to perform all of these steps on their own PC.
1. Log on to the Windows domain by signing in to your PC.
2. In IBM i Access Client Solutions on your PC, select Actions > Management > System Configurations.
3. On the System Configuration page, select System A and click Edit.
4. On the Connection tab, select Use kerberos authentication; do not prompt. Click OK. This will
allow IBM i Access Client Solutions connections to use the Kerberos principal name and password for
authentication.
5. On the System Configuration page, click Close.
6. Repeat these steps for System B.
Now that you have configured IBM i Access Client Solutions applications to use Kerberos authentication,
you can verify the single sign-on environment.
Verifying network authentication service and EIM configuration

Now that you have verified the individual pieces of your single sign-on configuration and ensured that
all setup is complete, you must verify that you have configured EIM and network authentication service
correctly and that single sign-on works as expected.
Note: When using the 5250 emulator in IBM i Access Client Solutions with Kerberos Authentication, you
need to change the Remote sign-on (QRMTSIGN) system value to *VERIFY to enable you to bypass the
sign-on. To change the Remote sign-on system value, follow these steps:

1. In IBM Navigator for i on System A, expand IBM i Management > Configuration and Service.
2. Click System Values.
3. Right-click Signon and select Properties.
4. On the Remote page, select Allow sign-on to be bypassed and Verify user ID on target system, and
click OK.
To verify that your single sign-on environment works correctly, have John Day follow these steps:
1. In IBM i Access Client Solutions,
a) On the System pull-down, select System A.
b) Expand General and click 5250 Emulator to open a connection to System A.
2. An emulator session is started for System A and no sign-on prompt displays. To verify the session
is signed on as JOHND, John Day's IBM i user profile, enter the DSPJOB command in the emulator
session and check that the USER: field shows JOHND.
IBM i Access Client Solutions 5250 emulator session successfully used EIM to map the jday Kerberos
principal to the JOHND System A user profile because of the associations defined for EIM identifier, John
Day. The emulator session for System A is now connected as JOHND.
(Optional) Postconfiguration considerations

Now that you finished this scenario, the only EIM user you have defined that EIM can use is the DN for the
LDAP administrator.
The LDAP administrator DN that you specified for the system user on System A has a high level of
authority to all data on the directory server. Therefore, you might consider creating one or more DNs
as additional users that have more appropriate and limited access control for EIM data. The number of
additional EIM users that you define depends on your security policy's emphasis on the separation of
security duties and responsibilities. Typically, you might create at least the two following types of DNs:
• A user that has EIM administrator access control
This EIM administrator DN provides the appropriate level of authority for an administrator who is
responsible for managing the EIM domain. This EIM administrator DN can be used to connect to the
domain controller when managing all aspects of the EIM domain by means of IBM Navigator for i.
• At least one user that has all of the following access controls:
– Identifier administrator
– Registry administrator
– EIM mapping operations
This user provides the appropriate level of access control required for the system user that performs
EIM operations on behalf of the operating system.
Note: To use this new DN for the system user instead of the LDAP administrator DN, you must change the
EIM configuration properties for each system. For this scenario, you need to change the EIM configuration
properties for any IBM i model that you set up.
Related information
Managing EIM configuration properties
Scenario: Enabling single sign-on for IBM i

View this scenario to learn how to configure network authentication service and EIM to create a single
sign-on environment across multiple systems in an enterprise. This scenario expands on the concepts and
Single sign-on 21
tasks presented in the previous scenario which demonstrates how to create a simple single sign-on test
environment.
Situation
You are a network administrator that manages a network and network security for your company,
including the Order Receiving department. You oversee the IT operations for a large number of employees
who take customer orders over the telephone. You also supervise two other network administrators who
help you maintain the network.
The employees in the Order Receiving department use Windows and IBM i and require multiple
passwords for the different applications they use every day. Consequently, you spend a lot of time
managing and troubleshooting problems related to passwords and user identities, such as resetting
forgotten passwords.
As the company's network administrator, you are always looking for ways to improve the business,
starting with the Order Receiving department. You know that most of your employees need the same type
of authority to access the application that they use to query inventory status. It seems redundant and
time consuming for you to maintain individual user profiles and numerous passwords that are required in
this situation. In addition, you know that all of your employees can benefit by using fewer user IDs and
passwords. You want to do these things:
• Simplify the task of password management for the Order Receiving department. Specifically, you want
to efficiently manage user access to the application your employees routinely use for customer orders.
• Decrease the use of multiple user IDs and passwords for the department employees, as well as for the
network administrators. However, you do not want to make the Windows IDs and IBM i user profiles the
same nor do you want to use password caching or synching.
Based on your research, you know that IBM i supports single sign-on, a solution that allows your users
to log on once to access multiple applications and services that normally require them to log on with
multiple user IDs and passwords. Because your users do not need to provide as many user IDs and
passwords to do their jobs, you have fewer password problems to solve for them. Single sign-on seems to
be an ideal solution because it allows you to simplify password management in the following ways:
• For typical users that require the same authority to an application, you can create policy associations.
For example, you want the order clerks in the Order Receiving department to be able to log on once with
their Windows user name and password and then be able to access a new inventory query application
in the manufacturing department without having to be authenticated again. However, you also want
to ensure that the level of authorization that they have when using this application is appropriate. To
attain this goal, you decide to create a policy association that maps the Windows user identities for this
group of users to a single IBM i user profile that has the appropriate level of authority for running the
inventory query application. Because this is a query-only application in which users cannot change data,
you are not as concerned about detailed auditing for this application. Consequently, you feel confidant
that using a policy association in this situation conforms to your security policy.
You create a policy association to map the group of order clerks with similar authority requirements to
a single IBM i user profile with the appropriate level of authority for the inventory query application.
Your users benefit by having one less password to remember and one less logon to perform. As the
administrator, you benefit by having to maintain only one user profile for user access to the application
instead of multiple user profiles for everyone in the group.
• For each of your network administrators who have user profiles with special authorities, such as
*ALLOBJ and *SECADM, you can create identifier associations. For example, you want all of the user
identities for a single network administrator to be precisely and individually mapped to one another
because of the administrator's high level of authority.
Based on your company's security policy, you decide to create identifier associations to map specifically
from each network administrator's Windows identity to his IBM i user profile. You can more easily
monitor and trace the activity of the administrator because of the one-to-one mapping that identifier
associations provide. For example, you can monitor the jobs and objects that run on the system for a
specific user identity. Your network administrator benefits by having one less password to remember

and one less logon to perform. As the network administrator, you benefit by tightly controlling the
relationships between all of your administrator's user identities.
This scenario has the following advantages:
• Simplifies authentication process for users.
• Simplifies managing access to applications.
• Eases the overhead of managing access to servers in the network.
• Minimizes the threat of password theft.
• Avoids the need for multiple signons.
• Simplifies user identity management across the network.
Objectives
In this scenario, you are the administrator at MyCo, Inc. who wants to enable single sign-on for the users
in the Order Receiving department.
The objectives of this scenario are as follows:
• System A and System B must participate in the MYCO.COM realm to authenticate the users and services
that are participating in this single sign-on environment. To enable the systems to use Kerberos, System
A and System B must be configured for network authentication service.
• The IBM Tivoli Directory Server for IBM i (LDAP) on System A must function as the domain controller for
the new EIM domain.
Note: Refer to domains to learn how two different types of domains, an EIM domain and a Windows
domain, fit into the single sign-on environment.
• All user identities in the Kerberos registry must map successfully to a single IBM i user profile with
appropriate authority for user access to the inventory query application.
• Based on your security policy, two administrators, John Day and Sharon Jones, who also have user
identities in the Kerberos registry, must have identifier associations to map these identities to their IBM
i user profiles which have *SECADM special authority. These one-to-one mappings enable you to closely
monitor the jobs and objects that run on the system for these user identities.
• A Kerberos service principal must be used to authenticate the users to the IBM i Access Client Solutions
applications.
Details
The following figure illustrates the network environment for this scenario.
Single sign-on 23
The figure illustrates the following points relevant to this scenario.
EIM domain data defined for the enterprise
• Three registry definition names:
– A registry definition name of MYCO.COM for the Windows server registry. You will define this when
you use the EIM configuration wizard on System A.
– A registry definition name of SYSTEMA.MYCO.COM for the IBM i registry on System A. You will define
this when you use the EIM configuration wizard on System A.
– A registry definition name of SYSTEMB.MYCO.COM for the IBM i registry on System B. You will define
this when you use the EIM configuration wizard on System B.
• Two default registry policy associations:
Note: EIM lookup operation processing assigns the highest priority to identifier associations. Therefore,
when a user identity is defined as a source in both a policy association and an identifier association, only
the identifier association maps that user identity. In this scenario, two network administrators, John
Day and Sharon Jones, both have user identities in the MYCO.COM registry, which is the source of the
default registry policy associations. However, as shown below, these administrators also have identifier
associations defined for their user identities in the MYCO.COM registry. The identifier associations
ensure that their MYCO.COM user identities are not mapped by the policy associations. Instead,
the identifier associations ensure that their user identities in the MYCO.COM registry are individually
mapped to other specific individual user identities.
– One default registry policy association maps all user identities in the Windows server registry called
MYCO.COM, to a single IBM i user profile called SYSUSERA in the SYSTEMA.MYCO.COM registry on
System A. For this scenario, mmiller and ksmith represent two of these user identities.

– One default registry policy association maps all user identities in the Windows server registry called
MYCO.COM, to a single IBM i user profile called SYSUSERB in the SYSTEMB.MYCO.COM registry on
System B. For this scenario, mmiller and ksmith represent two of these user identities.
• Two EIM identifiers named John Day and Sharon Jones to represent the two network administrators in
the company who have those names.
• For the John Day EIM identifier, these identifier associations are defined:
– A source association for the jday user identity, which is a Kerberos principal in the Windows server
registry.
– A target association for the JOHND user identity, which is a user profile in the IBM i registry on
System A.
– A target association for the DAYJO user identity, which is a user profile in the IBM i registry on System
B.
• For the Sharon Jones EIM identifier, these identifier associations are defined:
– A source association for the sjones user identity, which is a Kerberos principal in the Windows server
registry.
– A target association for the SHARONJ user identity, which is a user profile in the IBM i registry on
System A.
– A target association for the JONESSH user identity, which is a user profile in the IBM i registry on
System B.
Windows server
• Acts as the Kerberos server (kdc1.myco.com), also known as a key distribution center (KDC), for the
network.
• The default realm for the Kerberos server is MYCO.COM.
• All Microsoft Windows Active Directory users that do not have identifier associations are mapped to a
single IBM i user profile on each of the IBM i models.
System A
• The directory server on System A will be configured to be the EIM domain controller for the new EIM
domain, MyCoEimDomain.
• Participates in the EIM domain, MyCoEimDomain.
• Has the service principal name of krbsvr400/[email protected].
• Has the fully qualified host name of systema.myco.com. This name is registered in a single Domain
Name System (DNS) to which all PCs and servers in the network point.
• Home directories on System A store the Kerberos credentials caches for IBM i user profiles.
System B
• Has the fully qualified host name of systemb.myco.com. This name is registered in a single Domain
Name System (DNS) to which all PCs and servers in the network point.
• The principal name for System B is krbsvr400/[email protected].
• Participates in the EIM domain, MyCoEimDomain.
• Home directories on System B store the Kerberos credentials caches for IBM i user profiles.
Single sign-on 25
Administrative PC
• Runs Microsoft Windows operating system.
• Serves as the primary logon system for the administrator.
• Configured to be part of the MYCO.COM realm (Windows domain).

Successful completion of this scenario requires that the following assumptions and prerequisites are met:
1. All system requirements, including software and operating system installation, have been verified.
To verify that these licensed programs have been installed, complete the following:
a. In IBM Navigator for i, expand IBM i Management > Configuration and Service > Software.
b. Click Installed Products.
c. Ensure that all the necessary licensed programs are installed.
2. All necessary hardware planning and setup are complete.
3. TCP/IP and basic system security are configured and tested on each system.
4. The directory server and EIM should not be previously configured on System A.
Note: Instructions in this scenario are based on the assumption that the directory server has not been
previously configured on System A. However, if you already configured the directory server, you can
still use these instructions with only slight differences. These differences are noted in the appropriate
places within the configuration steps.
5. A single DNS server is used for host name resolution for the network. Host tables are not used for host
name resolution.
Note: The use of host tables with Kerberos authentication might result in name resolution errors or
other problems.
Configuration steps
Note: You need to thoroughly understand the concepts related to single sign-on, which include network
authentication service and Enterprise Identity Mapping (EIM) concepts, before you accomplish this
scenario. If you are ready to continue with this scenario complete the following steps:
Related tasks
Related information
EIM associations
Host name resolution
Completing the planning work sheets

The following planning work sheets are tailored to fit this scenario based on the general single sign-on
planning worksheets.
These planning work sheets demonstrate the information that you need to gather and the decisions you
need to make as you prepare to configure the single sign-on implementation described by this scenario.
To ensure a successful implementation, you must be able to answer Yes to all prerequisite items in the
work sheet and you should gather all the information necessary to complete the work sheets before you
perform any configuration tasks.

Note: You need to thoroughly understand the concepts related to single sign-on, which include network
scenario.

Is your system running IBM i 5.4, or later? Yes
Are the following options and licensed programs installed on Yes
System A and System B?
Have you installed an application that is enabled for single Yes

sign-on on each of the PCs that will participate in the single
sign-on environment?
Note: For this scenario, all of the participating PCs have IBM
i Access Client Solutions (5733-XJ1) installed. See IBM i
Access Client Solutions: Getting Started
Do you, the administrator, have *SECADM, *ALLOBJ, and Yes

Do you have one of the following systems acting as the Yes, Windows server
Kerberos server (also known as the KDC)? If yes, specify
which system.
1. Windows server
2. IBM i PASE (5.4 or later)
3. AIX server
4. z/OS
Are all your PCs in your network configured in a Windows Yes

domain?
Is the IBM i model time within 5 minutes of the system time Yes
on the Kerberos server? If not see, Synchronize system times.
Are you running IBM i PASE for the Kerberos server? You must have IBM Network
Authentication Enablement for i (5770-
NAE) installed.
You need this information to configure EIM and network authentication service on System A
Table 4. Single sign-on configuration planning work sheet for System A

Use the following information to complete the EIM Configuration wizard. The information in this work
sheet correlates with the information you need to supply for each page in the wizard:
How do you want to configure EIM for your system? Create and join a new domain
Single sign-on 27
Where do you want to configure the EIM domain? On the local directory server
Note: This will configure the directory
server on the same system on which you
are currently configuring EIM.

The Network Authentication Service wizard launches from the EIM Configuration wizard. Use the
following information to complete the Network Authentication Service wizard.
Note: A Windows server domain is similar to a Kerberos
realm.

What is the Kerberos server, also known as a key KDC: kdc1.myco.com
distribution center (KDC), for this Kerberos default realm? Port: 88
Kerberos server.

server?
password server.
• LDAP
• IBM i NetServer
What is the password for your service principal or systema123

principals?
own configuration.


Specify user information that the wizard should use when Port: 389
configuring the directory server. This is the connection Distinguished name:
user. You must specify the port number, administrator cn=administrator
distinguished name, and a password for the administrator. Password: mycopwd
Note: Specify the LDAP administrator's distinguished name
(DN) and password to ensure the wizard has enough
authority to administer the EIM domain and the objects in
it.
own configuration.
What is the name of the EIM domain that you want to MyCoEimDomain
create?
Which user registries do you want to add to the EIM Local IBM i
domain? --SYSTEMA.MYCO.COM
Kerberos--KDC1.MYCO.COM
Note: You should not select Kerberos

user identities are case sensitive when
the wizard presents this option.
Which EIM user do you want System A to use when User type: Distinguished name
performing EIM operations? This is the system user. Distinguished name:
Note: If you have not configured the directory server prior cn=administrator
to configuring single sign-on, the only distinguished name Password: mycopwd
(DN) you can provide for the system user is the LDAP
administrator's DN and password.
own configuration.
You need this information to allow System B to participate in the EIM domain and to configure network
authentication service on System B
Table 5. Single sign-on configuration planning work sheet for System B

Configuration planning work sheet for System B Answers
Use the following information to complete the EIM Configuration wizard for System B:
How do you want to configure EIM on your system? Join an existing domain
Single sign-on 29
Table 5. Single sign-on configuration planning work sheet for System B (continued)
following information to complete the Network Authentication Service wizard:
Note: You can launch the Network Authentication Service wizard independently of the EIM Configuration
wizard.

Note: A Windows server domain is equivalent to a Kerberos
realm.

What is the Kerberos server for this Kerberos default realm? KDC: kdc1.myco.com
What is the port on which the Kerberos server listens? Port: 88

Kerberos server.

server?
password server.
• LDAP
• IBM i NetServer
What is the password for your IBM i service principals? systemb123

own configuration.

service principals for System B to the Kerberos registry?
Use the following information to complete the EIM Configuration wizard for System B:
What is the name of the EIM domain controller for the EIM systema.myco.com
domain that you want to join?
Do you plan on securing the connection with SSL or TLS? No

Table 5. Single sign-on configuration planning work sheet for System B (continued)
What is the port on which the EIM domain controller listens? 389
Which user do you want to use to connect to the domain User type: Distinguished name and
controller? This is the connection user. password
Note: Specify the LDAP administrator's distinguished name Distinguished name:
(DN) and password to ensure the wizard has enough cn=administrator
authority to administer the EIM domain and the objects in Password: mycopwd
it.
own configuration.
What is the name of the EIM domain that you want to join? MyCoEimDomain
What is the name of the user registry that you want to add to Local IBM i --SYSTEMB.MYCO.COM
the EIM domain?
Which EIM user do you want System B to use when User type: Distinguished name and
performing EIM operations? This is the system user. password
Note: Earlier in this scenario, you used the EIM Distinguished name:
Configuration wizard to configure the directory server on cn=administrator
System A. In doing so, you created a DN and password Password: mycopwd
for the LDAP administrator. This is currently the only DN
defined for the directory server. Therefore, this is the DN and Note: Any and all passwords specified in
password you must supply here.
own configuration.
Table 6. Single sign-on configuration planning work sheet - user profiles

IBM i user profile name Password is specified Special authority System
(Privilege class)
SYSUSERA No User System A
SYSUSERB No User System B
Table 7. Single sign-on configuration planning work sheet - EIM domain data
Identifier name User registry User identity Association Identifier
type description
John Day MYCO.COM jday Source Kerberos
(Windows)
login user
identity
Single sign-on 31
Table 7. Single sign-on configuration planning work sheet - EIM domain data (continued)
Identifier name User registry User identity Association Identifier
type description
John Day SYSTEMA.MYCO.COM JOHND Target IBM i user
profile on
System A
John Day SYSTEMB.MYCO.COM DAYJO Target IBM i user
profile on
System B
Sharon Jones MYCO.COM sjones Source Kerberos
(Windows)
login user
identity
Sharon Jones SYSTEMA.MYCO.COM SHARONJ Target IBM i user
profile on
System A
Sharon Jones SYSTEMB.MYCO.COM JONESSH Target IBM i user
profile on
System B
Table 8. Single sign-on configuration planning work sheet - EIM domain data - policy associations
Policy Source user registry Target user registry User identity Description
association
type
Default MYCO.COM SYSTEMA.MYCO.COM SYSUSERA Maps
registry authenticated
Kerberos user to
appropriate IBM
i user profile
Default MYCO.COM SYSTEMB.MYCO.COM SYSUSERB Maps
registry authenticated
Kerberos user to
appropriate IBM
i user profile
Related information
Creating a basic single sign-on configuration for System A

The EIM Configuration wizard helps you create a basic EIM configuration and also opens the Network
Authentication Service wizard to allow you to create a basic network authentication service configuration.
Note: Instructions in this scenario are based on the assumption that the IBM Tivoli Directory Server for
IBM i has not been previously configured on System A. However, if you already configured the directory
server, you can still use these instructions with only slight differences. These differences are noted in the
appropriate places within the configuration steps.
Use the information from your work sheets to configure EIM and network authentication service on
System A. When you complete this step, you accomplish the following:
• Create a new EIM domain.
• Configure the directory server on System A to be the EIM domain controller.

• Configure network authentication service.
• Create EIM registry definitions for the IBM i registry and the Kerberos registry on System A.
• Configure System A to participate in the EIM domain.
1. In IBM Navigator for i on System A, expand IBM i Management > Security > All Tasks > Enterprise
Identity Mapping > Configuration.
2. Click Configure to start the EIM configuration wizard.
3. On the Welcome page, select Create and join a new domain. Click Next.
4. On the Specify EIM Domain Location page, select On the local Directory server. Click Next.
Note: This launches the Network Authentication Service wizard. With this wizard, you can
configure several IBM i interfaces and services to participate in the Kerberos realm.
c) On the Specify KDC Information page, enter kdc1.myco.com for the name of the Kerberos
server in the KDC field and enter 88 in the Port field. Click Next.
example, systema123. This password is used when the System A service principal is added to the
Kerberos server.
g) On the Create Batch File page, select Yes, specify the following information, and click Next:
• Batch file: Add the text systema to the end of the default batch file name. For example, /
QIBM/UserData/OS400/iSeriesNavigator/config/NASConfig_systema.bat.
file is run.
h) On the Summary page, review the network authentication service configuration details. Click
Finish.
6. On the Configure Directory Server page, enter the following information, and click Next.
Note: If you configured the directory server before you started this scenario, you will see the Specify
User for Connection page instead of the Configure Directory Server page. In that case, you must
specify the distinguished name and password for the LDAP administrator.
• Port: 389
Single sign-on 33
7. On the Specify Domain page, enter the name of the domain in the Domain field. For example,
MyCoEimDomain.
8. On the Specify Parent DN for Domain page, select No. Click Next.
Note: If the directory server is active, a message is displayed that indicates you need to end and
restart the directory server for the changes to take effect. Click Yes to restart the directory server.
9. On the Registry Information page, select Local IBM i and Kerberos. Click Next. Write down the
Note:
Note: Because you did not configure the directory server prior to performing the steps in this
scenario, the only distinguished name (DN) that you can choose is the LDAP administrator's DN.
11. On the Summary page, confirm the EIM configuration information. Click Finish.
You have completed a basic EIM and network authentication service configuration on System A. The next
step is to configure System B to participate in the EIM domain that you just created
Configuring System B to participate in the EIM domain and configure System

B for network authentication service
After you have created a new domain and configured network authentication service on System A, you
need to configure System B to participate in the EIM domain and configure network authentication service
on System B.
Use the information from your work sheets to complete this step.
1. In IBM Navigator for i on System B, expand IBM i Management > Security > All Tasks > Enterprise
Identity Mapping > Configuration.
2. Click Configure to start the EIM configuration wizard.
3. On the Welcome page, select Join an existing domain. Click Next.
Note: This launches the Network Authentication Service wizard. This wizard allows you to
configure several IBM i interfaces and services to participate in a Kerberos network.
c) On the Specify KDC Information page, enter kdc1.myco.com for the name of the Kerberos
server in the KDC field and enter 88 in the Port field. Click Next.

example, systema123. This password will be used when the System A service principal is added
to the Kerberos server.
g) On the Create Batch File page, select Yes, specify the following information, and click Next.
• Batch file: Add the text systemb to the end of the default batch file name. For example, /
QIBM/UserData/OS400/iSeriesNavigator/config/NASConfig_systemb.bat.
file is run.
h) On the Summary page, review the network authentication service configuration details. Click
Finish.
5. On the Specify Domain Controller page, specify the following information, and click Next.
• Domain controller name: systema.myco.com
• Port: 389
6. On the Specify User for Connection page, specify the following information, and click Next
Note: Specify the LDAP administrator's DN and password that you created earlier in this scenario on
System A.
7. On the Specify Domain page, select the name of the domain that you want to join. Click Next. For
example, MyCoEimDomain.
8. On the Registry Information page, select Local IBM i and deselect Kerberos registry. (The Kerberos
registry was created when you created the MyCoEimDomain domain.) Click Next. Write down the
Note:
Note: Specify the LDAP administrator's DN and password that you created earlier in this scenario on
System A.
Single sign-on 35
10. On the Summary page, confirm the EIM configuration. Click Finish.
You have now configured System B to participate in the domain and to use network authentication
service.
Adding both IBM i service principals to the Kerberos server

You can use one of two methods to add the necessary IBM i service principals to the Kerberos server.
You can manually add the service principals or, as this scenario illustrates, you can use a batch file to add
them. You created this batch file in Step 2. To use this file, you can use the IFS download function in IBM
Navigator for i to copy the file to the Kerberos server and run it.
Follow these steps to use the batch files to add principal names to the Kerberos server:
Download the batch files created by the wizard to your Kerberos server.
As the administrator on your Windows server do the following:
a) In IBM Navigator for i on System A, expand IBM i Management > File Systems > Integrated File
System > Root > QIBM > UserData > OS400 > iSeriesNavigator > config
b) Right-click NASConfig_systema.bat and select Download.
c) Click the Download button on the Confirm Download page.
d) Save the file, this will put it in your browser's download location. Refer to your browser's
documentation for how to customize the download folder location. Usually this is the Downloads
folder.
Note: It is recommended that you now delete the NASConfig_systema.bat file from System A.
e) Repeat these steps on System B to download NASConfig_systemb.bat to theWindows server.
Run both batch files on kdc1.myco.com
1. On your Windows server, open the directory where you downloaded the batch files.
2. Find the NASConfig_systema.bat file and double click the file to run it.
3. Repeat these steps for NASConfig_systemb.bat.
4. After each file runs, verify that the IBM i principal has been added to the Kerberos server by
completing the following:
a. On your Windows server, expand Administrative Tools > Active Directory Users and Computers >
Users.
b. Verify the IBM i model has a user account by selecting the appropriate Windows domain.
Note: This Windows domain should be the same as the default realm name that you specified in the
network authentication service configuration.
c. In the list of users that is displayed, find systema_1_krbsvr400 and systemb_1_krbsvr400. These
are the user accounts generated for the IBM i principal name.
d. (Optional) Access the properties on your Active Directory user. From the Delegation tab, select
Trust this user for delegation to any service (Kerberos only).
Note: This optional step enables your system to delegate, or forward, a user's credentials to other
systems. As a result, the IBM i service principal can access services on multiple systems on behalf
of the user. This is useful in a multi-tier network.
Now that you have added the IBM i service principals to the Kerberos server, you can create user profiles
on the IBM i model.

Creating user profiles on System A and System B
You want all of your users in the MYCO.COM Kerberos registry to map to a single IBM i user profile on each
of your IBM i model.
Therefore, you need to create an IBM i user profile on System A and System B. Use the information from
your work sheets to create a user profile for these users:
1. In IBM Navigator for i on System A, expand IBM i Management > User and Groups.
2. Click Users.
3. On Actions pull-down, select New > User.
4. On the New User dialog box, enter SYSUSERA in the User name field.
5. In the Password field, select No password (sign-on not allowed).
6. Click Capabilities.
7. On the Privileges page, select User in the Privilege class field. Click OK and click Add.
Repeat these steps on System B, but enter SYSUSERB in the User name field.
Now that you have created the user profiles on System A and System B, you can create the home
directories for all of the IBM i user profiles.
Creating home directories on System A and System B

Each user that connects to a IBM i model and applications needs a directory in the /home directory. This
directory stores the user's Kerberos credentials cache.
To create a home directory for a user, complete the following:
On the System A command line, enter: CRTDIR '/home/user profile' where user profile is the
IBM i user profile name for the user. For example: CRTDIR '/home/SYSUSERA'. This creates a home
directory for the user profile on System A that represents all the Active Directory users.
Repeat this command on System B but specify SYSUSERB to create a home directory for the user profile
on System B.
Now that you have created the home directories, you can test the network authentication service
configuration on the systems.
Testing network authentication service on System A and System B

After you complete the network authentication service configuration tasks for both of your systems, you
need to verify that your configurations work correctly for both System A and System B.
You can do this testing by completing these steps to request a ticket granting ticket for the System A and
System B principals:
Note: Ensure that you have created a home directory for your IBM i user profile before performing this
procedure.
1. On a command line, enter QSH to start the Qshell Interpreter.
2. Enter keytab list to display a list of principals registered in the keytab file. In this scenario,
krbsvr400/[email protected] should display as the principal name for System A.
3. Enter kinit -k krbsvr400/[email protected] to request a ticket-granting ticket
from the Kerberos server. By running this command, you can verify that your IBM i model has been
configured properly and that the password in the keytab file matches the password stored on the
Kerberos server. If this is successful then the kinit command will display without errors.
4. Enter klist to verify that the default principal is krbsvr400/[email protected]. This
command displays the contents of a Kerberos credentials cache and verifies that a valid ticket has
been created for the IBM i model service principal and placed within the credentials cache on the
system.
Single sign-on 37
Ticket cache: FILE:/QIBM/USERDATA/OS400/NETWORKAUTHENTICATION/creds/krbcred
Default principal: krbsvr400/[email protected]
Server: krbtgt/[email protected]
Valid 200X/06/09-12:08:45 to 20XX/11/05-03:08:45
$
Repeat these steps using the service principal name for System B: krbsvr400/
[email protected]
Now that you have tested network authentication service on System A and System B, you can create an
EIM identifier for each of the administrators.
Creating EIM identifiers for two administrators, John Day and Sharon Jones
In this scenario, you create two EIM identifiers, one named John Day and the other named Sharon Jones.
As part of setting up your single sign-on test environment, you need to create EIM identifiers for two of
your administrators so they can both log on to IBM i environments using their Windows user identities.
To create the EIM identifiers, follow these steps:
Identity Mapping.
4. Right-click Identifiers and select New Identifier.
5. On the New EIM Identifier dialog box, enter John Day in the Identifier field.
6. Click OK.
Repeat steps 2 through 6, but enter Sharon Jones in the Identifier field.
Now that you have created an EIM identifier for each of the administrators, you must create identifier
associations that map user identities to the identifiers. First, create the identifier associations for John
Day.
Creating identifier associations for John Day

You must create the appropriate associations between the EIM identifier, John Day, and the user
identities that the person represented by the identifier uses. These identifier associations, when properly
configured, enable the user to participate in a single sign-on environment.
In this scenario, you need to create one source association and two target associations for the John Day
identifier:
• A source association for the jday Kerberos principal, which is the user identity that John Day, the
person, uses to log in to Windows and the network. The source association allows the Kerberos principal
to be mapped to another user identity as defined in a corresponding target association.

• A target association for the JOHND IBM i user profile, which is the user identity that John Day, the
person, uses to log in to IBM i model and to other IBM i applications on System A. The target association
specifies that a mapping lookup operation can map to this user identity from another one as defined in a
source association for the same identifier.
• A target association for the DAYJO IBM i user profile, which is the user identity that John Day, the
person, uses to log in to IBM Navigator for i and other IBM i applications on System B. The target
association specifies that a mapping lookup operation can map to this user identity from another one as
defined in a source association for the same identifier.
Use the information from your planning work sheets to create the associations.
To create the source association for John Day's Kerberos principal, follow these steps:
Identity Mapping.
4. Right-click Identifiers and select Open.
5. Right-click John Day and select Properties.
6. On the Associations page, click Add.
7. In the Add Association dialog box, specify or Browse to select the following information, and click OK.
• Registry: MYCO.COM
• User: jday
• Association type: Source
8. Click OK to close the Add Associations dialog box.
To create a target association for John Day's IBM i user profile on System A, follow these steps:
2. In the Add Association dialog box, specify or Browse to select the following information, and click OK:
• Registry: SYSTEMA.MYCO.COM
• User: JOHND
• Association type: Target
To create a target association for John Day's IBM i user profile on System B, follow these steps:
2. In the Add Association dialog box, specify or Browse to select the following information, and click OK:
• Registry: SYSTEMB.MYCO.COM
• User: DAYJO
Single sign-on 39
4. Click OK to close the Properties dialog box.
Now that you have created the identifier associations that map John Day's user identities to his EIM
identifier, you can create similar associations for Sharon Jones.
Creating identifier associations for Sharon Jones

You must create the appropriate associations between the EIM identifier, Sharon Jones, and the
user identities that the person represented by the identifier uses. These associations, when properly
configured, enable the user to participate in a single sign-on environment.
In this scenario, you need to create one source association and two target associations for the Sharon
Jones identifier:
• A source association for the sjones Kerberos principal, which is the user identity that Sharon Jones, the
person, uses to log in to Windows and the network. The source association allows the Kerberos principal
to be mapped to another user identity as defined in a corresponding target association.
• A target association for the SHARONJ IBM i user profile, which is the user identity that Sharon Jones,
the person, uses to log in to IBM Navigator for i and other IBM i applications on System A. The target
• A target association for the JONESSH IBM i user profile, which is the user identity that Sharon Jones,
the person, uses to log in to IBM Navigator for i and other IBM i applications on System B. The target
Use the information from your planning work sheets to create the associations:
To create the source association for Sharon Jones' Kerberos principal, follow these steps:
Identity Mapping.
4. Right-click Identifiers and select Open.
5. Right-click Sharon Jones and select Properties.
7. On the Add Association dialog box, specify or Browse to select the following information, and click
OK.
• Registry: MYCO.COM
• User: sjones
• Association type: Source
To create a target association to Sharon Jones' IBM i user profile on System A, follow these steps:

OK:
• Registry: SYSTEMA.MYCO.COM
• User: SHARONJ
To create a target association to Sharon Jones' IBM i user profile on System B, follow these steps:
OK:
• Registry: SYSTEMB.MYCO.COM
• User: JONESSH
7. Click OK to close the Properties dialog box.
Now that you have created the identifier associations that map Sharon Jones' user identities to her EIM
identifier, you can create the default registry policy associations that map all of your Kerberos registry
users to a specific user profile in each of the IBM i model user registries.
Creating default registry policy associations

You want to have all your Microsoft Active Directory users on the Windows server map to the user profile,
SYSUSERA, on System A and to the user profile, SYSUSERB, on System B.
Fortunately, you can use policy associations to create mappings directly between a group of users and
a single target user identity. In this case, you can create a default registry policy association the maps
all the user identities (for which no identifier associations exist) in the MYCO.COM Kerberos registry to a
single IBM i user profile on System A.
You need two policy associations to accomplish this goal. Each policy association uses the MYCO.COM
user registry definition as the source of the association. However, each policy association maps user
identities in this registry to different target user identities, depending on which IBM i model the Kerberos
user accesses:
• One policy association maps the Kerberos principals in the MYCO.COM user registry to a target user of
SYSUSERA in the target registry of SYSTEMA.MYCO.COM.
• The other policy association maps the Kerberos principals in the MYCO.COM user registry to a target
user of SYSUSERB in the target registry of SYSTEMB.MYCO.COM.
Use the information from your planning works sheets to create two default registry policy associations.
Note: Before you can use policy associations, however, you must first ensure that you enable the domain
to use policy associations for mapping lookup operations. You can do this as part of the process for
creating your policy associations, as follows:
Identity Mapping.
3. Right-click MyCoEimDomain, and select Mapping policy.
4. On the General page, select the Enable mapping lookups using policy associations for domain
MyCoEimDomain.
Follow these steps to create the default registry policy association for the users to map to the SYSUSERA
user profile on System A:
Single sign-on 41
1. On the Registry page, click Add.
2. In the Add Default Registry Policy Association dialog box, specify or Browse to select the following
information, and click OK:
• Target user: SYSUSERA
3. Click OK to close the Mapping Policy dialog box.
Follow these steps to create the default registry policy association for the users to map to the
SYSUSERB user profile on System B:
4. On the Registry page, click Add.
5. In the Add Default Registry Policy Association dialog box, specify or Browse to select the following
information, and click OK:
• Target registry: SYSTEMB.MYCO.COM
• Target user: SYSUSERB
6. Click OK to close the Mapping Policy dialog box.
Now that you have created the default registry policy associations, you can enable the registries to
participate in lookup operations and to use the policy associations.
Enabling registries to participate in lookup operations and to use policy

associations
EIM allows you to control how each registry participates in EIM. Because a policy association can have
a large scale effect within an enterprise, you can control whether a registry can be affected by policy
associations.
Also, you can control whether a registry can participate in mapping lookup operations at all. To use policy
associations for a registry, you must enable their use for that registry as well as enable that registry to
participate in lookup operations. To enable registries to use policy associations and participate in lookup
operations, complete these steps:
To enable the MYCO.COM registry to participate in mapping lookup operations, follow these steps:
Identity Mapping.
4. Right-click User Registries and select Open.
5. Right-click the MYCO.COM registry and select Mapping Policy.
6. On the General page, select Enable mapping lookups for registry MYCO.COM, and click OK.

To enable the SYSTEMA.MYCO.COM registry to participate in mapping lookup operations and to use policy
associations, follow these steps:
Identity Mapping
4. Right-click User Registries and select Open.
5. Right-click the SYSTEMA.MYCO.COM registry and select Mapping Policy.
6. On the General page, select Enable mapping lookups for registry SYSTEMA.MYCO.COM, select Use
policy associations, and click OK.
Repeat these steps to enable the SYSTEMB.MYCO.COM registry to participate in mapping lookup
operations and to use policy associations, but on the General page, select Enable mapping lookups
for registry SYSTEMB.MYCO.COM, select Use policy associations, and click OK.
Now that you have completed the EIM configuration for your registries and users, you should test the
resulting mappings to ensure that they work as planned.
Testing EIM identity mappings

Now that you have created all the associations that you need, you must verify that EIM mapping lookup
operations return the correct results based on the configured associations.
For this scenario, you must test the mappings used for the identifier associations for each of the
administrators and you must test the mappings used for the default registry policy associations. To test
the EIM mappings, follow these steps:
Test mappings for John Day
To test that identifier mappings work as expected for John Day, follow these steps:
Identity Mapping.
4. On the Test a mapping dialog box, specify or Browse to select the following information, and click
Test.
• Source user: jday
5. Results will display in the Mapping found portion of the page, as follows:

Target user JOHND
Single sign-on 43
6. Click Close.
Repeat these steps but select SYTEMB.MYCO.COM for the Target registry field. Results will display in
the Mapping found portion of the page, as follows:

Target user DAYJO
Test mappings for Sharon Jones

To test the mappings used for the individual associations for Sharon Jones, follow these steps:
Identity Mapping.
Test:
• Source user: sjones

Target user SHARONJ
Origin EIM Identifier: Sharon Jones
6. Click Close.
Repeat these steps but select SYSTEMB.MYCO.COM for the Target registry field. Results will display in
the Mapping found portion of the page, as follows:

Target user JONESSH
Origin EIM Identifier: Sharon Jones
Test mappings used for default registry policy associations

To test that mappings work as expected for the users in the Order Receiving Department, as based on the
policy associations that you defined, follow these steps:

Identity Mapping.
Test:
• Source user: mmiller

Target user SYSUSERA
Origin Registry policy association
6. Click Close.
To test the mappings used for the default registry policy association that maps your users to the
SYSUSERB profile on System B, follow these steps:
Identity Mapping.
Test:
• Source user: ksmith
• Target registry: SYSTEMB.MYCO.COM
Single sign-on 45
Target user SYSUSERB
Origin Registry policy association
6. Click Close.
If you receive messages or errors that indicate problems with your mappings or with communications, see
Troubleshoot EIM to help you find solutions to these problems.
Now that you have tested the EIM identity mappings, you can configure IBM i Access for Windows
applications to use Kerberos authentication.
Configuring IBM i Access Client Solutions applications to use Kerberos

authentication
You must use Kerberos to authenticate before you can use IBM i Access Client Solutions applications to
access your system. Therefore, from your PC, you need to configure IBM i Access Client Solutions to use
Kerberos authentication.
To configure IBM i Access Client Solutions applications to use Kerberos authentication, complete the
following steps:
Note: Each of your users needs to perform all of these steps on their own PC.
1. Log on to the Windows domain by signing in to your PC.
2. In IBM i Access Client Solutions on your PC, select Actions > Management > System Configurations.
3. On the System Configuration page, select System A and click Edit.
4. On the Connection tab, select Use kerberos authentication; do not prompt. Click OK. This will
allow IBM i Access Client Solutions connections to use the Kerberos principal name and password for
authentication.
5. On the System Configuration page, click Close.
6. Repeat these steps for System B.
Now that you have configured IBM i Access Client Solutions applications to use Kerberos authentication,
you can verify the single sign-on environment.
Verifying network authentication service and EIM configuration

Now that you have verified the individual pieces of your single sign-on configuration and ensured that
all setup is complete, you must verify that you have configured EIM and network authentication service
correctly and that single sign-on works as expected.
Note: When using the 5250 emulator in IBM i Access Client Solutions with Kerberos Authentication, you
need to change the Remote sign-on (QRMTSIGN) system value to *VERIFY to enable you to bypass the
sign-on. To change the Remote sign-on system value, follow these steps:
1. In IBM Navigator for i on System A, expand IBM i Management > Configuration and Service .
2. Click System Values.
3. Right-click Signon and select Properties.
4. On the Remote page, select Allow sign-on to be bypassed and Verify user ID on target system, and
click OK.
5. Repeat these steps on System B.
Verify that your single sign-on environment works correctly.
Have John Day follow these steps:
a) On the System pull-down, select System A.

b) Expand General and click 5250 Emulator to open a connection to System A.
2. An emulator session is started for System A and no sign-on prompt displays. To verify the session
is signed on as JOHND, John Day's IBM i user profile, enter the DSPJOB command in the emulator
session and check that the USER: field shows JOHND.
Note: IBM i Access Client Solutions 5250 emulator session successfully used EIM to map the jday
Kerberos principal to the JOHND System A user profile because of the associations defined for EIM
identifier, John Day. The emulator session for System A is now connected as JOHND.
Have Sharon Jones follow these steps:
a. On the System pull-down, select System A.
b. Expand General and click 5250 Emulator to open a connection to System A.
2. An emulator session is started for System A and no sign-on prompt displays. To verify the session is
signed on as SHARONJ, Sharon Jones' IBM i user profile, enter the DSPJOB command in the emulator
session and check that the USER: field shows SHARONJ.
Note: IBM i Access Client Solutions 5250 emulator session successfully used EIM to map the sjones
Kerberos principal to the SHARONJ System A user profile because of the associations defined for EIM
identifier, Sharon Jones. The emulator session for System A is now connected as SHARONJ.
(Optional) Postconfiguration considerations

Now that you finished this scenario, the only EIM user you have defined that EIM can use is the DN for the
LDAP administrator.
The LDAP administrator DN that you specified for the system user on System A has a high level of
authority to all data on the directory server. Therefore, you might consider creating one or more DNs
as additional users that have more appropriate and limited access control for EIM data. The number of
additional EIM users that you define depends on your security policy's emphasis on the separation of
security duties and responsibilities. Typically, you might create at least the two following types of DNs:
• A user that has EIM administrator access control
This EIM administrator DN provides the appropriate level of authority for an administrator who is
responsible for managing the EIM domain. This EIM administrator DN can be used to connect to the
domain controller when managing all aspects of the EIM domain by means of IBM Navigator for i.
• At least one user that has all of the following access controls:
– Identifier administrator
– Registry administrator
– EIM mapping operations
This user provides the appropriate level of access control required for the system user that performs
EIM operations on behalf of the operating system.
Note: To use this new DN for the system user instead of the LDAP administrator DN, you must change the
EIM configuration properties for each system. For this scenario, you need to change the EIM configuration
properties for any IBM i model that you set up.
Scenario: Enabling single sign-on for ISV applications

View this information to review scenarios that illustrate typical single sign-on implementation situations
to help you plan your own certificate implementation as part of your server security policy.
Situation
You are the lead application developer for an independent software vendor (ISV), and are responsible
for overseeing the applications that your company develops and delivers to IBM i Access Client Solutions
customers. You know that IBM i Access Client Solutions provides your customers with the capability
Single sign-on 47
of creating and participating in a single sign-on environment. You want your applications to leverage
these single sign-on capabilities because you feel it will help sell your product. You decide to market an
application called Calendar to IBM i Access Client Solutions customers that use network authentication
service and Enterprise Identity Mapping (EIM) to create their single sign-on environment. The Calendar
application allows users to view and manage their workday schedule. Enabling the Calendar application
for single sign-on requires you to include server specific code within your application which enables it
to participate within a single sign-on environment. You have previous experience creating applications
that call EIM APIs, but this will be your first time working with an application that also calls network
authentication service APIs.
Note: It is also possible to develop applications for a single sign-on environment that use a different
authentication method. For example, you can insert the necessary code for authenticating with digital
certificates, or for binding the directory server, instead of inserting the necessary code for authenticating
with network authentication service.
Objectives
You want to be able to market your Calendar application to IBM i Access Client Solutions customers who
are interested in applications that are capable of participating in a single sign-on environment. You want
to enable the server side of the Calendar application to participate in a single sign-on environment. You
have the following objectives, as you complete this scenario:
• You want to change the server specific part of an existing Calendar application or develop a new
Calendar application which participates in a single sign-on environment that uses EIM and network
authentication service.
• You want to create a single sign-on environment in which you can test your application.
• You want to test your Calendar application and ensure that it successfully participates in a single
sign-on environment.

Implementation of this scenario depends on the following assumptions and prerequisite conditions:
• You want your Calendar application to participate in a single sign-on environment that is configured to
use Kerberos and EIM.
• You already have experience creating applications for the IBM i Access Client Solutions platform.
• You have configured your IBM i system to participate in a Kerberos realm.
• You write applications in one of the following languages:
– You use an ILE programming language, such as C, to write your applications and you are familiar with
the GSS API set.
– You use Java to write your applications and you are familiar with the JGSS API set.
Note: You might also require the Java toolbox, depending on which set of JGSS APIs you use.
• You have already completed the client-specific portion of your application, enabling it to use Kerberos
authentication.
Configuration steps
Related information
Programming
Generic Security Service API
IBM® Java Generic Security Service (JGSS)

Completing the planning prerequisite worksheet
Complete the following planning worksheet to ensure that you have met the prerequisites for a successful
single sign-on environment in which you can test your application.
Prerequisite worksheet Answers

Is your system running IBM i 5.4, or later? Yes
Do you have *SECADM, *ALLOBJ, and *IOSYSCFG special Yes
authorities?
Do you have one of the following servers acting as the Kerberos Yes
server? If yes, specify which one.
1. Microsoft Windows server Server
3. AIX server
4. z/OS
For Windows server Server, do you have Windows Support Yes

Tools (which provides the ktpass tool) installed?
Are all of the PCs that you want to be able to participate in Yes
a single sign-on environment in your network configured in an
IBM i domain?
Is the IBM i model time within 5 minutes of the system time on Yes
the Kerberos server? If not see, Synchronize system times.
Writing a new application or change an existing application

You are ready to begin including the server specific code that enables your Calendar application to
participate in an single sign-on environment.
Using your previous programming experience with EIM APIs, you create a program flow similar to this
one:
• Application Initialization
– EIM Get Handle
– EIM Connect
• Processing Loop
– Wait for user request
– Authenticate user using Kerberos
– Call EIM to map from network authentication service user to Local user
– Swap to local user
– Perform Task
– Swap back to original user
– Go to "Wait for user request"
Note: This scenario assumes that you have already created or changed the client specific code to
enable your application for an IBM i single sign-on environment, and therefore only provides the
steps required to complete the server specific part of your program.
• Application Termination
– Destroy EIM Handle
Single sign-on 49
See the ISV code examples for example pseudocode and snippets that you can use to help complete the
server specific part of your program. When you have added the necessary client and server specific code
to your Calendar application, you can create a single sign-on test environment to test it.
Creating a single sign-on test environment

To create a test environment for single sign-on you must complete a different scenario before you can
complete this scenario.
Complete the Scenario: Create a single sign-on test environment. This scenario demonstrates how to
configure network authentication service and EIM to create a basic single sign-on test environment.
This scenario guides you through the following steps to configure and work with a simple single sign-on
environment:
1. Complete necessary planning work sheets.
2. Create a basic single sign-on configuration for the IBM i system.
3. Add the IBM i service principal to the Kerberos server.
4. Create a home directory for a test user, John Day, on the IBM i system.
5. Test the network authentication service configuration on the IBM i system.
6. Create an EIM identifier for John Day.
7. Create a source association and a target association for the new EIM identifier.
8. Test the EIM identity mappings.
9. Configure IBM i Access Client Solutions applications to use Kerberos.
10. Verify network authentication service and EIM configuration.
After you have created the single sign-on test environment the scenario describes, you can test your
Calendar application to ensure that it works correctly.
Testing your application

You have completed the development of both client and server specific updates to your Calendar
application, enabling it for an IBM i single sign-on environment. You are now ready to test it.
Follow these steps to verify that you have created an application that participates successfully in a single
signon environment:
1. Log the test user jday (this user was created in the create a single sign-on test environment scenario)
into the Windows domain by signing him into a PC.
2. Have the test user open your Calendar application on the PC. If the calendar opens, the application
has used EIM to map the jday Kerberos principal to the JOHND IBM i user profile because of the
associations defined for EIM identifier, John Day. The Calendar application session for the IBM i
model is now connected as JOHND, and you have successfully enabled your ISV application for an IBM
i single sign-on environment.
Related concepts
enterprise.
Example: ISV code

This information displays sample code for writing a kerberos server along with calling EIM apis to map
from a kerberos principal to an IBM i user profile.
IBM grants you a nonexclusive copyright license to use all programming code examples from which you
can generate similar function tailored to your own specific needs.

All sample code is provided by IBM for illustrative purposes only. These examples have not been
thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability,
or function of these programs.
All programs contained herein are provided to you "AS IS" without any warranties of any kind. The
implied warranties of non-infringement, merchantability and fitness for a particular purpose are expressly
disclaimed.
Note: By using the code examples, you agree to the terms of the “Code license and disclaimer
information” on page 68.
/*** START OF SPECIFICATIONS *************************************/

/* */
/* MODULE NAME: Kerberos/EIM server sample */
/* */
/* DESCRIPTION: Below is sample code for writing a Kerberos server */
/* along with calling EIM APIs to map from a Kerberos */
/* principal to an IBM i user profile. */
/* */
/* NOTE: Error checking has been removed. */
/*********************************************************************/
/* #include files removed here */
//---------------------------------------------------------------------
// EIM assumptions:
// On the IBM i where this program is running the EIM configuration
// information has been set. The information used by this program
// is:
// - ldapURL
// - local registry
// EIM ldap lookup connection
// - The ldap connection information needed for doing the mapping
// lookups in this program can be stored in a validation list
// or other user secure space. Here we will just hard code
// pretend values.
// - This connection will only be used for a lookup operation so
// the ldap user only needs EIM mapping lookup authroity.
// All EIM data (Identifiers and associations) has been added.
//----------------------------------------------------------------------
#define LDAP_BINDDN "cn=mydummmy"

#define LDAP_BINDPW "special"
//----------------------------------------------------------------------
//
// Function: l_eimError
// Purpose: EIM error has occurred. This function will print out the
// EIM error message.
//
//----------------------------------------------------------------------
void l_eimError(char * function, EimRC * err)
{
char * msg = NULL;
printf("EIM ERROR for function = %s.\n", function);
msg = eimErr2String(err);
printf(" %s\n",msg);
free(msg);
}
//----------------------------------------------------------------------
//
// Function: l_eimConnect
// Purpose: Get an EIM handle and connect to the ldap server.
//
//----------------------------------------------------------------------
int l_eimConnect(EimHandle * handle)
{
int rc = 0;
char eimerr[150];
EimRC *err = (EimRC *)&eimerr;
Single sign-on 51
EimConnectInfo con;
/* This needs to be at least 48. */

err->memoryProvidedByCaller = 150;
//------------------------------------------------------------------
// Create handle. We will pass NULL for the URL indicating that we
// will use the information that was configured for the system.
//------------------------------------------------------------------
eimCreateHandle(handle,
NULL,
err);
//------------------------------------------------------------------
// Connect
//------------------------------------------------------------------
// The ldap user id and password might be stored in a validation
// list or other user secure space. Here we will just hard code
// pretend values.
// You can also choose to use Kerberos authentication when
// connecting to ldap. You will first need to verify your ldap
// server is set up to accept kerberos authentication.
//------------------------------------------------------------------
// This connection will only be used for a lookup operation so the
// ldap user only needs EIM mapping lookup authroity.
//------------------------------------------------------------------
con.type = EIM_SIMPLE;
con.creds.simpleCreds.protect = EIM_PROTECT_NO;
con.creds.simpleCreds.bindDn = LDAP_BINDDN;
con.creds.simpleCreds.bindPw = LDAP_BINDPW;
con.ssl = NULL;
eimConnect(handle,
con,
err);
return 0;
}
//----------------------------------------------------------------------
//----------------------------------------------------------------------
//
// Function: getIBMiUser
// Purpose: Get IBM i user associated with the kerberos user and exchange
// to the user.
//
//----------------------------------------------------------------------
int getIBMiUser(EimHandle * handle,
char * IBMiUser,
gss_buffer_desc * client_name)
{
char * principal;
char * realm;
char * atsign;
//------------------------------------------------------------------
//
// Get principal and realm from the kerberos client_name.
//
//------------------------------------------------------------------
// client_name.value contains string of principal@realm. Get
// pointer to each piece.
//------------------------------------------------------------------
principal = client_name->value;
atsign = strchr(principal, '@');
*atsign = 0x00; // NULL end the principal
realm = atsign + 1; // Advance pointer to the realm
//------------------------------------------------------------------
//
// Call EIM to get the target user associated with the kerberos
// source user. This sample application assumes that the
// kerberos realm name is also the name of the EIM registry
// defining this realm.
//
//------------------------------------------------------------------
listPtr = (EimList *)listBuff;
for (i = 0; i < 2; i++)
{
if (0 != (rc =
eimGetTargetFromSource(handle,
realm,

principal,
NULL, // use configured
// local
// registry.
NULL,
listSize,
listPtr,
err)))
{
l_eimError("eimGetTargetFromSource", err);
return -1;
}
if (listPtr->bytesAvailable == listPtr->bytesReturned)
break;
else
{
listSize = listPtr->bytesAvailable;
freeStorage = malloc(listSize);
listPtr = (EimList *)freeStorage;
}
}
// Check the number of entries found, if 0 no mapping exists

// otherwise extract user profile from buffer and cleanup
// storage
return 0;
/********************************************************************/
/* Function Name: get_kerberos_credentials_for_server */
/* */
/* Descriptive Name: Basically this function finds the keytab entry */
/* for this server. It will use this to validate */
/* the tokens received. */
/* */
/* Input: char * service_name - the service name. */
/* gss_buffer_t msg_buf - the input message */
/* Output: */
/* gss_cred_id_t *server_creds - The output credential */
/* */
/* Exit Normal: return value == 0 */
/* Exit Error: -1, error was encountered, */
/********************************************************************/
int get_kerberos_credentials_for_server (
char * service_name, /* name of service principal*/
gss_cred_id_t * server_creds) /* credential acquired */
{
gss_buffer_desc name_buf; /* buffer for import name */
gss_name_t server_name; /* gss service name */
OM_uint32 maj_stat, /* GSS status code */
min_stat; /* Mechanism kerberos status */
/* Convert service name to GSS internal format */

name_buf.value = service_name;
name_buf.length = strlen((char *)name_buf.value) + 1;
maj_stat = gss_import_name(
&min_stat, /* kerberos status */
&name_buf, /* name to convert */
(gss_OID) gss_nt_service_name, /* name type */
&server_name); /* GSS internal name */
/* Acquire credentials for the service from keytab */

maj_stat = gss_acquire_cred(
&min_stat, /* kerberos status */
server_name, /* gss internal name */
GSS_C_INDEFINITE, /* max credential life */
GSS_C_NULL_OID_SET, /* use default mechanism */
GSS_C_ACCEPT, /* credential usage */
server_creds, /* output cred handle */
NULL, /* ignore actual mech */
NULL); /* ignore time remaining */
/* Release the gss internal format name */

gss_release_name(&min_stat, &server_name);
return 0;
}
/********************************************************************/
Single sign-on 53
/* Function Name: do_kerberos_authentication() */
/* Purpose: Any valid client request is accepted. If a context */
/* is established, its handle is returned in context and */
/* the client name is returned. */
/* */
/* Exit Normal: return value == 0 */
/* Exit Error: -1, error was encountered, */
/********************************************************************/
int do_kerberos_authentication (
int s, /* socket connection */
gss_cred_id_t server_creds, /* credentials for the server */
gss_ctx_id_t * context, /* GSS context */
gss_buffer_t client_name) /* kerberos principal */
{
gss_buffer_desc send_tok, /* token to send to client */
recv_tok; /* token received from client */
gss_name_t client; /* client principal */
min_stat; /* Mechanism (kerberos) status*/
msgDesc_t msgSend, /* Message buffer to send */
msgRecv; /* Message buffer received */
gss_OID doid;
*context = GSS_C_NO_CONTEXT; /* initialize the context */
do {
/* Receive the message from the client */
memset(&msgRecv, 0x00, sizeof(msgRecv));
if (0 != recvAmessage(s, &msgRecv))
return -1;
recv_tok.length = msgRecv.dataLength;
recv_tok.value = msgRecv.buffer;
/* Accept the security context */

maj_stat = gss_accept_sec_context(
min_stat, /* kerberos status */
context, /* context handle */
server_creds, /* acquired server creds*/
&recv_tok, /* token received */
GSS_C_NO_CHANNEL_BINDINGS, /* no CB */
&client, /* client requestor */
NULL, /* ignore mech type */
&send_tok, /* token to be sent */
NULL, /* ignore ctx flags */
NULL, /* ignore time_rec */
NULL); /* ignore delegated cred*/
/* release the received token */

gss_release_buffer(&min_stat, &recv_tok);
/* Check to see if there is a token client wants mutual

authentication. */
if (send_tok.length != 0)
{
/* Send the token message to the other side */

/* release the send token buffer */
}
} while (maj_stat == GSS_S_CONTINUE_NEEDED);
/* client name is returned - extract client from ticket. This

client name will be used to map to the IBM i user profile */
maj_stat = gss_display_name(&min_stat, client, client_name, &doid);
maj_stat = gss_release_name(&min_stat, &client);
return 0;
}
/********************************************************************/
/* */
/* Function Name: getTestPort() */
/* */
/* Descriptive Name: get the port on which the server is listening */
/* */
/* Input: char * service - the service name. If null, looks */
/* for kerb-test-server. */
/* */
/* Output: none */
/* */
/* Exit Normal: return value == port number */
/* */

/* Exit Error: N/A */
/* */
/********************************************************************/
CLINKAGE int getTestPort(char *name)
{
struct servent service;
struct servent_data servdata;
char defaultName[] = "krb-test-server", *servName;
char tcp[] = "tcp";
int retPort, rc;
memset(&servdata, 0x00, sizeof(servdata));
memset(&service, 0x00, sizeof(service));
if (name == NULL)
servName = defaultName;
else
servName = name;
rc = getservbyname_r(servName, tcp, &service,
&servdata);
if (rc != 0)
retPort = DEFAULT_KERB_SERVER_PORT;
else
retPort = service.s_port;
return ntohl(retPort);
} /* end getPort */
/********************************************************************/
/* */
/* Function Name: getListeningSocket() */
/* */
/* Descriptive Name: get a listening socket created and return it. */
/* */
/* Input: none. */
/* */
/* Output: listening socket created. */
/* */
/* Exit Normal: return value == listening socket. */
/* */
/* Exit Error: -1, error was encountered. */
/* */
/* NOTE: Error checking removed */
/* */
/********************************************************************/
CLINKAGE int getListeningSocket(void)
{
int rc, sd, option;
struct sockaddr_in sin;
sd = socket(AF_INET, SOCK_STREAM, 0)
option = 1;
setsockopt(sd, SOL_SOCKET, SO_REUSEADDR,

(char *)&option, sizeof(option));
memset(&sin, 0x00, sizeof(sin));

sin.sin_family = AF_INET;
sin.sin_port = htons(getTestPort(NULL));
bind(sd, (struct sockaddr *)&sin, sizeof(sin));
listen(sd, SOMAXCONN);
return sd;
} /* end getListeningSocket() */
/********************************************************************/
/* */
/* Function Name: getServerSocket() */
/* */
/* Descriptive Name: get a server socket that is connected to a */
/* client. This routine blocks waiting for */
/* the client. */
/* */
/* Input: int lsd - listening socket. */
/* */
/* Output: server socket created. */
/* */
/* Exit Normal: return value == server socket. */
/* */
Single sign-on 55
/* */
/* */
/* */
/********************************************************************/
CLINKAGE int getServerSocket(int lsd)
{
return accept(lsd, NULL, 0);
} /* end getServerSocket() */
/********************************************************************/
/* */
/* Function Name: main */
/* */
/* Descriptive Name: Driver for the server program which performs */
/* kerberos authentication and EIM mapping. */
/* */
/* Input: char* service_name - name of service requested */
/* */
/* Exit Normal: 0 = success */
/* */
/* */
/* */
/* */
/********************************************************************/
int main(int argc, char **argv)
{
int ssd, /* server socket */
lsd; /* listening socket */
char *service_name; /* name of service (input) */
gss_cred_id_t server_creds; /* server credentials to acquire */
gss_ctx_id_t context; /* GSS context */
min_stat; /* Mechanism (kerberos) status */
gss_buffer_desc client_name; /* Client principal establishing
context. */
char IBMiUser[10];
char save_handle[SY_PH_MAX_PRFHDL_LEN]; // *CURRENT profile handle
char client_handle[SY_PH_MAX_PRFHDL_LEN];// Swap to profile handle
EimHandle eimHandle;
Qus_EC_t errorcode;
memset(errorcode, 0x00, 256);
errorcode->Bytes_Provided = 256;
service_name = argv[1];
/*------------------------------------------------------------------
// Kerberos setup
// Acquire credentials for the service
//----------------------------------------------------------------*/
get_kerberos_credentials_for_server(service_name, &server_creds);
/*------------------------------------------------------------------
// get a listening socket
//----------------------------------------------------------------*/
lsd = getListeningSocket();
/*------------------------------------------------------------------
// EIM setup
// Connect to eim
// ----------------------------------------------------------------*/
l_eimConnect(&eimHandle);
/*-------------------------------------------------------------------
// Save a copy of the current user so we can swap back to it
// after each request
// ----------------------------------------------------------------*/
QsyGetProfileHandleNoPwd(save_handle,
"*CURRENT ",
"*NOPWD ",
&errorcode);
/*------------------------------------------------------------------
// Loop waiting for requests on the socket
//----------------------------------------------------------------*/
do { /* loop until the application or the system is ended */
/* Save the profile handle of the current user */

/* Accept a TCP connection */
ssd = getServerSocket(lsd);
/* -----------------------------------------------------------------
// Establish context with the client and get the client name.
//------------------------------------------------------------------
// The client name contains the kerberos principal and realm. In
// EIM these equate to the source user and source registry.
//--------------------------------------------------------------- */
do_kerberos_authentication(ssd,
server_creds,
&context,
&client_name);
/*------------------------------------------------------------------
// Perform eim mapping lookup operation to get the associated
// IBM i user.
//--------------------------------------------------------------- */
getIBMiUser(&eimHandle,
IBMiUser,
&client_name);
/* -----------------------------------------------------------------
// Swap to the user returned from EIM lookup
// ---------------------------------------------------------------- */
QsyGetProfileHandleNoPwd(client_handle,
client_name,
"*NOPWDCHK ",
&errorcode);
QsySetToProfileHandle(client_handle, &errorcode);
/* -----------------------------------------------------------------
// do the real work of the application here as the application is
// now running under an appropriate user profile
// ---------------------------------------------------------------- */
// Call or code application specific behavior here.
/* -----------------------------------------------------------------
// reset the process to run under the original user profile
// ---------------------------------------------------------------- */
QsySetToProfileHandle(save_handle, &errorcode);
} while (1)
eimDestroy_handle(&eimHandle);
gss_delete_sec_context(&min_stat, &context, NULL);

close(ssd);
close(lsd);
gss_release_cred(&min_stat, &server_creds);
return 0;
}
Planning for single sign-on

The single sign-on planning process identifies the software and hardware prerequisites required to
implement single sign-on in your enterprise.
You must plan carefully to create a single sign-on environment that meets the needs of your enterprise.
There are several decisions that you must make while planning out an IBM i single sign-on environment.
One such decision is if you want to create policy associations. The security concerns of your enterprise
factor heavily on this type of decision.
Here are some resources that you can use to complete the planning stage for your single sign-on
environment:
After you have adequately planned for your single sign-on environment, you can configure your single
Related tasks
Single sign-on 57
Related information
Planning Enterprise Identity Mapping for IBM i
Requirements for configuring a single sign-on environment

Your system must meet the following hardware and software prerequisites before implementing a single
Requirements for IBM i 5.4, or later

To create a successful single sign-on environment, ensure that all these requirements are met:
• IBM i 5.4, or later, is installed.
• Latest IBM i program temporary fixes (PTFs) are applied.
• IBM i Host Servers (5770-SS1 Option 12) is installed.
• Qshell Interpreter (5770-SS1 Option 30) is installed.
• TCP/IP and basic system security are configured.
If you intend to use the Synchronize Functions wizard in System i® Navigator to propagate an existing
single sign-on configuration across multiple systems or if you intend to configure Management Central
servers for single sign-on using System i Navigator, ensure all these requirements are met:
• IBM i 5.4, or later, is installed.
• Latest IBM i program temporary fixes (PTFs) are applied.
• IBM i Access for Windows 5.4, or later, is installed.
• Latest IBM i Access for Windows service pack is installed.
For information about acquiring the latest service pack, see, IBM i Support web page .
• IBM i Host Servers (5770-SS1 Option 12) is installed.
• Qshell Interpreter (5770-SS1 Option 30) is installed.
• TCP/IP and basic system security are configured.
• If you intend to use the Synchronize Functions wizard, configure the systems to use Secure Sockets
Layer (SSL) to protect the transmission of sensitive configuration information, such as passwords.TCP/IP
and basic system security are configured.
Client PC requirements
• Microsoft Windows is used.
• IBM i Access Client Solutions (5733-XJ1) is installed.
• TCP/IP is configured.
If you intend to use the Synchronize Functions wizard in System i Navigator to propagate an existing
single sign-on configuration across multiple systems or if you intend to configure Management Central
servers for single sign-on using System i Navigator, ensure all these requirements are met:
• Microsoft Windows operating system is used.
• IBM i Access for Windows, 5.4, or later, is installed.
– Network component of System i Navigator is installed on PC that administers single sign-on.
– Security component of System i Navigator is installed on PC that administers single sign-on.
• Latest IBM i Access for Windows service pack is installed.

For information about acquiring the latest service pack, see, IBM i Support web page .
Microsoft Windows server requirements

• Hardware planning and setup are completed.
• Windows server is used.
• Windows Support Tools (which provides the ktpass tool) is installed.
• Windows domain is configured.
• Users within the network are added to a Windows domain through Microsoft Windows Active Directory.
You can use the provided planning work sheets to help you gather information and make decisions for
your single sign-on implementation. Each work sheet contains a list of tasks that need to be completed.
Single sign-on planning worksheets

Complete these worksheets to ensure that you have met all of the prerequisites for single sign-on and
that you have considered all of the aspects of your particular system and its security requirements.
Before you use these configuration planning worksheets, you need to plan your overall single sign-on
implementation. Use these configuration planning worksheets to ensure that you have met all of the
prerequisites, and that you have taken into consideration all of the aspects of your particular IBM i
environment.
Single sign-on prerequisite worksheet

This detailed work sheet is provided to help you ensure that you meet all hardware and software
prerequisites for implementing single sign-on. To ensure a successful implementation, you must be able
to answer Yes to all prerequisite items in the work sheet and you should gather all the information
necessary to complete the work sheets before you perform any configuration tasks.

Is your system running IBM i 5.4, or later?
Are the following options and licensed programs installed on
your server?
• IBM i Access for Windows (5770-XE1), if you intend to use
the Synchronize Functions wizard in System i Navigator to
propagate an existing single sign-on configuration across
multiple systems or if you intend to configure Management
Central servers for single sign-on using System i Navigator.
Have you installed an application that is enabled for single sign-

on on each of the PCs that will participate in the single sign-on
environment?
Note: For the scenarios in this information, all of the PCs have
IBM i Access Client Solutions (5733-XJ1) installed. See IBM i
Access Client Solutions: Getting Started
Single sign-on 59
Table 9. Single sign-on prerequisite work sheet (continued)
If you intend to use the Synchronize Functions wizard in
System i Navigator to propagate an existing single sign-on
configuration across multiple systems or if you intend to
configure Management Central servers for single sign-on using
System i Navigator :
• Is System i Navigator installed on the administrator's PC?
• Is the Security subcomponent of System i Navigator installed
on the administrator's PC?
• Is the Network subcomponent of System i Navigator installed
on the administrator's PC?
• Have you installed the latest IBM i Access for Windows
service pack? For the latest service pack, see, IBM i Support
web page .
Do you, the administrator, have *SECADM, *ALLOBJ, and

Do you have one of the following systems acting as the
Kerberos server (also known as the KDC)? If yes, specify which
system.
1. Windows server
3. AIX server
4. z/OS
Are all your PCs in your network configured in a Windows

domain?
Have you applied the latest program temporary fixes (PTFs)?
Is the IBM i model time within 5 minutes of the system time on
the Kerberos server? If not, see Synchronize system times.
Single sign-on configuration planning worksheet

This is a configuration planning worksheets, designed to ensure that you have met all of the hardware and
software prerequisites for single sign-on. Additionally, this worksheet ensures that you have completed
those Enterprise Identity Mapping (EIM) and network authentication service configuration tasks that are
required for a successful single sign-on environment.
Note: The single sign-on configuration planning worksheet is designed to assist you with the
implementation of a single sign-on environment based on Enterprise Identity Mapping (EIM) and network
authentication services. If you intend to use a different authentication mechanism, such as IBM Tivoli
Directory Server for IBM i or digital certificates, you might need to adapt portions of this work sheet to
better suit your needs.
Table 10. Single sign-on configuration planning work sheet

Configuration planning work sheet Answers

Table 10. Single sign-on configuration planning work sheet (continued)
How do you want to configure EIM for your system?
Where do you want to configure your EIM domain?

Do you want to configure network authentication service?
following information to complete the Network Authentication Service wizard:
Note: The Network Authentication Service wizard can also be launched independently of the EIM
Configuration wizard.
What is the name of the Kerberos default realm to which

your system will belong?
Note: A Windows domain is similar to a Kerberos realm.
Are you using Microsoft Active Directory?

What is the Kerberos server, also known as a key
distribution center (KDC), for this Kerberos default realm?
Do you want to configure a password server for this default
What is name of the password server for this Kerberos

server?
What is the port on which the password server listens?
For which services do you want to create keytab entries?

• LDAP
• IBM i NetServer
What is the password for your service principal or

principals?
Do you want to create a batch file to automate adding the
Do you want to include passwords with the IBM i service
Specify user information that the wizard should use when
configuring the directory server. This is the connection
user. You must specify the port number, administrator
distinguished name, and a password for the administrator.
Single sign-on 61
Table 10. Single sign-on configuration planning work sheet (continued)
What is the name of the EIM domain that you want to
create?
Do you want to specify a parent DN for the EIM domain?
Which user registries do you want to add to the EIM
domain?
Which EIM user do you want System A to use when
performing EIM operations? This is the system user.
After you complete the EIM Configuration wizard, use the following information to complete the
remaining steps required for configuring single sign-on:
What is the IBM i user profile name for the user?
What is the name of the EIM identifier that you want to
create?
What kinds of associations do you want to create?
What is the name of the user registry that contains the
Kerberos principal for which you are creating the source
association?
What is the name of the user registry that contains the
IBM i user profile for which you are creating the target
association?
What information do you need to supply to test EIM identity
mapping?
Related tasks

In the case of IBM i single sign-on solutions, the authentication method is network authentication service
(Kerberos).
Because a single sign-on environment can be complex to configure, you might find it useful to create
a test environment before you implement single sign-on across your enterprise. The create a test
single sign-on environment scenario demonstrates how to configure such a test environment so that
you can learn more about the planning needs of implementing single sign-on as well as gain a better
understanding of how a single sign-on environment can work for you.
After you work with a test environment, you can use what you learn to plan how to implement single
sign-on on a larger scale in your enterprise. You might find it useful to work through the enable single
sign-on for IBM i scenario to learn about the more advanced configuration options that you can employ
when you implement a single sign-on environment.
After you have reviewed these and the other single sign-on scenarios, you can use the single sign-on
planning worksheets to create an informed single sign-on implementation plan that fits the needs of your

enterprise. With these planning worksheets in hand, you are ready to continue with the configuration
process.
Configuring single sign-on involves a number of detailed configuration steps, this information describes
the high-level configuration tasks for single sign-on and provides links to the more detailed configuration
information for both EIM and network authentication service where appropriate.
Perform these tasks to configure a single sign-on environment:
1. Create your Windows domain
a) Configure the KDC on the Active Directory (AD) Server.
Note: You can choose to create and run your KDC on IBM i PASE rather than create a Windows
domain and run the KDC on a windows server.
b) Add IBM i service principals to the Kerberos server.
c) Create a home directory for each Kerberos user who will participate in your single sign-on
environment.
d) Verify TCP/IP domain information.
2. Create an EIM domain by running the both the network authentication service wizard and the EIM
configuration wizard on a server.
When you have completed these wizards, you have actually accomplished the following tasks:
a) Configured IBM i interfaces to accept Kerberos tickets.
b) Configured the Directory server on IBM i to be the EIM domain controller.
c) Created an EIM domain.
d) Configured a user identity for IBM i and IBM i applications to use when conducting EIM operations.
e) Added a registry definition to EIM for the local IBM i registry and the local Kerberos registry (if
Kerberos is configured).
3. For servers running IBM i 5.4, or later, see the Scenario: Propagate network authentication service and
EIM across multiple systems for a detailed demonstration on how to use the Synchronize Functions
wizard in System i Navigator to propagate a single sign-on configuration across multiple servers in a
mixed IBM i release environment.
Administrators can save time by configuring single sign-on once and propagating that configuration to
all of their systems instead of configuring each system individually.
4. Finish your configuration for the network authentication service.
Based on your single sign-on implementation plan, create a home directory for users on your servers.
5. Based on your implementation plan, customize your EIM environment by setting up associations for
the user identities in your enterprise.
a) Configure other servers to participate in the EIM domain.
b) Create EIM identifiers and identifier associations as needed.
c) Add additional registry definitions as needed.
d) Create policy associations as needed.
6. Test your single sign-on configuration.
To verify that you have configured the network authentication service and EIM correctly, sign on to the
system with a user ID, and then start a 5250 emulator session from IBM i Access Client Solutions. If no
IBM i sign-on prompt displays, EIM successfully mapped the Kerberos principal to an identifier on the
domain.
Note: If you find that your test of your single sign-on configuration fails, there might be a problem with
your configuration. You can troubleshoot single sign-on and learn how to recognize and fix common
problems with your single sign-on configuration.
Related concepts
Single sign-on 63
enterprise.
Scenario: Enabling single sign-on for IBM i
View this scenario to learn how to configure network authentication service and EIM to create a single
sign-on environment across multiple systems in an enterprise. This scenario expands on the concepts and
tasks presented in the previous scenario which demonstrates how to create a simple single sign-on test
environment.
Single sign-on planning worksheets
Complete these worksheets to ensure that you have met all of the prerequisites for single sign-on and
that you have considered all of the aspects of your particular system and its security requirements.
Related tasks
Planning for single sign-on
The single sign-on planning process identifies the software and hardware prerequisites required to
implement single sign-on in your enterprise.
Troubleshooting single sign-on
Use the following troubleshooting methods to solve some of the basic problems you might experience
while configuring and using a single sign-on environment.
Related information
Configuring network authentication service
Configuring Enterprise Identity Mapping
Managing single sign-on

Use network authentication service and Enterprise Identity Mapping (EIM) to manage your single sign-on
environment.
After you implement a single sign-on environment, you might need to perform various management tasks
to maintain that environment in accordance with your security policy just as you would any other aspect of
your network.
To learn more about how to manage these functions to maintain your single sign-on environment, review
the following:
• Manage network authentication service
Learn about common network authentication service management tasks such as how to synchronize
system times, add and delete realms, add a Kerberos server, and more.
• Manage EIM
Learn about common EIM management tasks, such as how to manage associations, identifiers, registry
definitions, and more.
If you experience problems with your single sign-on environment, you can roubleshoot single sign-on.
Related tasks

There are several actions that you can take to circumvent problems with your IBM i single sign-on
configuration:

1. You can confirm that your network authentication service configuration is correct by performing the
qshell kinit command.
To do this, enter the qshell environment and issue the kinit -k <service name> command. This
command uses the keytab entry that was created in the network authentication service wizard. This
command verifies that the encrypted password for the service is the same password that is stored on
the KDC. If this command does not complete successfully, revisit your network authentication service
configuration.
2. Verify your host name resolution configurations, including your DNS servers.
3. Verify the EIM system configuration information on each IBM i system that performs mapping lookup
operations.
a) In IBM Navigator for i, expand IBM i Management > Network > All Tasks > Enterprise Identity
Mapping.
b) Click Configuration.
c) Right-click the Domain Controller with which you want to work and select Properties.
d) On the Domain page, verify the domain connection settings and click Verify Configuration. This
verifies that the domain controller is active and that the settings for the domain controller are
correct.
e) On the System User page, click Verify Connection to verify that the system user is specified
correctly.
4. Verify defined EIM associations by using the test EIM mapping function to verify that the associations
you have defined provide the mappings you expect.
5. If your single sign-on configuration includes a multiple tier network, verify that ticket delegation is
enabled for the server in the middle tier. This is required for the middle tier server to forward user
credentials to the next server. You can enable ticket delegation on the Active Directory or Kerberos
server. An example of a multiple tier network is a PC which authenticates with one server and then
connects to another server.
If you are still experiencing a problem with your single sign-on after reviewing the steps above, use the
following table to determine possible solutions to the symptoms of your configuration problems:
Table 11. Troubleshooting table

Symptoms Possible solutions
Host name resolution problems
You are unable to connect to IBM i • This might be due to host resolution problems. Verify that the PC
systems within your single sign-on and your IBM i resolve to the same host name. Verify your host
environment. name resolution configurations, including your DNS server.
• This might be due to NAS configuration problems. See the
Troubleshoot network authentication service information in the
IBM i Information Center.
The NSLOOKUP utility fails to The NSLOOKUP utility uses the currently configured DNS to resolve
resolve a host name when given IP addresses from host names, as well as host names from IP
an IP address during an attempt addresses. If a host name cannot be resolved from an IP address,
to confirm that the host resolution the most likely cause is a missing PTR record in DNS. Have your
is consistent between your IBM i DNS administrator add a PTR record for this IP address.
system and a client PC.
EIM configuration problems
Single sign-on 65
Table 11. Troubleshooting table (continued)
EIM mappings are not working • The domain controller is inactive. Activate the domain controller.
as expected. In some instances,
• The EIM configuration is incorrect on the systems that you are
you are unable to sign into your
trying to use Kerberos authentication with or get mappings for.
system with IBM i Access Client
Verify your EIM configuration. On the system you are trying to
Solutions when using Kerberos
authenticate with, expand Network > All Tasks > Enterprise
authentication.
Identity Mapping. Click Configuration. Right-click the Domain
Controller with which you want to work and select Properties.
Verify the following:
– Domain page:
- The domain controller name and port numbers are correct.
- Click Verify Configuration to verify that the domain
controller is active.
- The local registry name is specified correctly.
- The Kerberos registry name is specified correctly.
- Verify that Enable EIM operations for this system is
selected.
– System user page:
- The specified user has sufficient EIM access control to
perform a mapping lookup, and the password is valid for the
user. See the online help to learn more about the different
types of user credentials.
Note: Whenever passwords are updated in the directory
server, they must also be updated in the system
configuration.
- Click Verify Connection to confirm that the user information
specified is correct.
• The EIM domain configuration is incorrect:
Note: You can test EIM mapping to help verify that the
associations for your EIM domain are properly configured.
– A target or source association for an EIM identifier is not set
up correctly. For example, there is no source association for
the Kerberos principal (or Windows user) or it is incorrect.
Or, the target association specifies an incorrect user identity.
Display all identifier associations for an EIM identifier to verify
associations for a specific identifier.
– A policy association is not set up correctly. Display all
policy associations for a domain to verify source and target
information for all policy associations defined in the domain.
– Mapping lookups are returning more than one target identity,
indicating that ambiguous mappings are configured. Test EIM
mappings to identify which mappings are incorrect.
– The registry definition and user identities do not match
because of case sensitivity. You can delete and re-create
the registry, or delete and re-create the association with the
proper case.

• EIM support is not enabled.

– EIM has been disabled for the system. Verify that Enable
EIM operations for this system is selected on the Domain
page for the system EIM configuration properties by expanding
Network > All Tasks > Enterprise Identity Mapping. Click
Configuration. Right-click the Domain Controller with which
you want to work and select Properties.
– Policy association support is not enabled at the domain level.
You might need to enable policy associations for a domain.
– Mapping lookup support or policy association support is
not enabled at the individual registry level. You might need
to enable mapping lookup support and the use of policy
associations for the target registry.
Network authentication service configuration problems
A keytab entry is not found • This can be due to a host resolution problem on the IBM i. If
when you perform a keytab you are using a host table, perform the Configure TCP/IP CFGTCP
list. command, option 10 (Work with TCP/IP host table entries) and
verify that the primary host name is listed first for the IP address
of the server.
• Verify your host name resolution configurations, including your
DNS server.
Users are unable to connect to Users might be unable to connect to systems if the EIM registry
systems. definition for the Kerberos registry was inappropriately defined as
case sensitive. Delete and re-create the Kerberos registry.
Note: You will lose any associations that have been defined for that
registry and will have to re-create them.
User receives a message The password for the service in the KDC does not match the
indicating an incorrect password for the service in the keytab. Update the keytab entry
password when verifying the by using the keytab add command, and update the password for
network authentication service the service on the KDC.
configuration.
User receives the following Verify that a home directory (/home/<user profile>) exists
message: Unable to for the user that is performing the kinit.
obtain name of default
credentials cache.
User receives the following Update the network authentication service configuration to use TCP
message: Response too large as the data communications protocol:
for datagram.
1. Using IBM Navigator for i, for the system that issued
the message, expand Security > All Tasks > Network
Authentication Service.
2. Click Properties.
3. On the General page, select Use TCP and click OK.
General problems
Single sign-on 67
You receive error message • Use the help associated with the text to resolve the problem.
CWBSY10XX when attempting
• Use the System Access detail trace feature to determine if the
single sign-on.
appropriate Kerberos ticket is retrieved.
• Download the Microsoft kerbtray utility to verify that the user has
Kerberos credentials.
• If single sign-on is failing, check the QZSOSIGN jobs in the
QUSRWRK subsystem. Search through the jobs for a CPD3E3F
message. If you find the CPD3E3F message, use the recovery
information provided within the message. The diagnostic
message contains both major and minor status codes to indicate
where the problem occurred. The most common errors are
documented in the message along with the recovery.
• If PC5250 is failing, check the following:
– Check the QTVDEVICE jobs for the CPD3E3F message.
– Check the QRMTSIGN system value and verify that it is set to
*VERIFY or *SAMEPRF.
Related information
RFC 1713: Tools for DNS debugging
Troubleshoot EIM.
Configuring network authentication service
Testing EIM mappings
Related information for Single sign-on

IBM Redbooks® publications and other information center topic collections contain information that
relates to the Single sign-on topic collection. You can view or print any of the PDF files.
IBM Redbooks
The IBM System i Security Guide for IBM i5/OS Version 5 Release 4 IBM Redbooks publication
provides a chapter on authentication using Single sign-on.
Other information
• Enterprise Identity Mapping (EIM)
• Network authentication services
• IBM Tivoli Directory Server for IBM i
• Digital Certificate Manager
Code license and disclaimer information

IBM grants you a nonexclusive copyright license to use all programming code examples from which you
can generate similar function tailored to your own specific needs.
SUBJECT TO ANY STATUTORY WARRANTIES WHICH CANNOT BE EXCLUDED, IBM, ITS PROGRAM
DEVELOPERS AND SUPPLIERS MAKE NO WARRANTIES OR CONDITIONS EITHER EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT, REGARDING THE PROGRAM OR
TECHNICAL SUPPORT, IF ANY.
UNDER NO CIRCUMSTANCES IS IBM, ITS PROGRAM DEVELOPERS OR SUPPLIERS LIABLE FOR ANY OF
THE FOLLOWING, EVEN IF INFORMED OF THEIR POSSIBILITY:
1. LOSS OF, OR DAMAGE TO, DATA;
2. DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES, OR FOR ANY ECONOMIC CONSEQUENTIAL
DAMAGES; OR
3. LOST PROFITS, BUSINESS, REVENUE, GOODWILL, OR ANTICIPATED SAVINGS.
SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF DIRECT, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES, SO SOME OR ALL OF THE ABOVE LIMITATIONS OR EXCLUSIONS MAY NOT
APPLY TO YOU.
Single sign-on 69
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to:
IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of
the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Corporation
Software Interoperability Coordinator, Department YBWA
3605 Highway 52 N
Rochester, MN 55901
U.S.A.
© Copyright IBM Corp. 2004, 2013 71

Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information is for planning purposes only. The information herein is subject to change before the
products described become available.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform
for which the sample programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs.
© Copyright IBM Corp. _enter the year or years_.
Programming interface information

This Single sign-on publication documents intended Programming Interfaces that allow the customer to
write programs to obtain the services of IBM i.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at
"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
72 Notices
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks of Oracle, Inc. in the United States, other
countries, or both.
Other product and service names might be trademarks of IBM or other companies.
Terms and conditions

Permissions for the use of these publications is granted subject to the following terms and conditions.
Personal Use: You may reproduce these publications for your personal, noncommercial use provided that
all proprietary notices are preserved. You may not distribute, display or make derivative works of these
publications, or any portion thereof, without the express consent of IBM.
Commercial Use: You may reproduce, distribute and display these publications solely within your
enterprise provided that all proprietary notices are preserved. You may not make derivative works of
these publications, or reproduce, distribute or display these publications or any portion thereof outside
your enterprise, without the express consent of IBM.
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either
express or implied, to the publications or any information, data, software or other intellectual property
contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use
of the publications is detrimental to its interest or, as determined by IBM, the above instructions are not
being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable
laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS
ARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,
AND FITNESS FOR A PARTICULAR PURPOSE.
Notices 73
IBM®
Product Number: 5770-SS1

Single Signon

Uploaded by

Copyright:

Available Formats

Single Signon

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Single Signon

Uploaded by

Copyright:

Available Formats

IBM i

What's new for IBM i 7.2

How to see what's new or changed

PDF file for Single sign-on

Saving PDF files

Downloading Adobe Reader

© Copyright IBM Corp. 2004, 2013 1

Single sign-on overview

Benefits for users

Benefits for administrators

Benefits for application developers

2 IBM i: Single sign-on

Employee Source Users Target users Employee System A User Comments

4 IBM i: Single sign-on

6 IBM i: Single sign-on

IBM i enablement of single sign-on

Network authentication service

8 IBM i: Single sign-on

Scenarios: Single sign-on

Scenario: Creating a single sign-on test environment

The figure illustrates the following points relevant to this scenario.

10 IBM i: Single sign-on

Prerequisites and assumptions

Completing the planning work sheets

Table 1. Single sign-on prerequisite work sheet

Do you, the administrator, have *SECADM, *ALLOBJ, and Yes

12 IBM i: Single sign-on

Are all your PCs in your network configured in a Windows Yes

Table 2. Single sign-on configuration planning work sheet for System A

Do you want to configure network authentication service? Yes

What is the name of the Kerberos default realm to which MYCO.COM

Are you using Microsoft Active Directory? Yes

Do you want to configure a password server for this default Yes

What is the password for your service principal or systema123

Do you want to create a batch file to automate adding the Yes

14 IBM i: Single sign-on

Note: The Kerberos principals stored

Creating a basic single sign-on configuration for System A

16 IBM i: Single sign-on

Adding System A service principal to the Kerberos server

Creating home directory for John Day on System A

Testing network authentication service configuration on System A

18 IBM i: Single sign-on

Creating an EIM identifier for John Day

Testing EIM identity mappings

For these fields See these results

Configuring IBM i Access Client Solutions applications to use Kerberos

Verifying network authentication service and EIM configuration

20 IBM i: Single sign-on

(Optional) Postconfiguration considerations

Scenario: Enabling single sign-on for IBM i

22 IBM i: Single sign-on

24 IBM i: Single sign-on

Prerequisites and assumptions

Completing the planning work sheets

26 IBM i: Single sign-on

Table 3. Single sign-on prerequisite work sheet

Have you installed an application that is enabled for single Yes

Do you, the administrator, have *SECADM, *ALLOBJ, and Yes

Are all your PCs in your network configured in a Windows Yes

Do you, the administrator, have SECADM, ALLOBJ, and Yes

Do you, the administrator, have SECADM, ALLOBJ, and Yes

/* START OF SPECIFICATIONS ***********************************/

context = GSS_C_NO_CONTEXT; / initialize the context */