| Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
This chapter provides instructions for setting up Windows Native Authentication (WNA) with OC4J to allow transparent authentication for Web application clients. Users must be familiar with Kerberos as well as Active Directory to complete the instructions in this chapter.
The following topics are covered:
Step 1: Configure the Linux Host System as a Kerberos Client
Step 3: Generate and Test the Keytab File for the Linux Host
WNA allows desktop clients using Microsoft Internet Explorer (or any browser that supports Microsoft's SPNEGO protocol) to automatically authenticate with Web applications using their Windows desktop credentials. OC4J Web applications can be configured to use WNA instead of challenging users for login credentials.
WNA uses a Kerberos session ticket that is generated when logging into the Windows desktop. The ticket is not visible to the user and contains, among other things, login credentials. The ticket is passed through the browser to the web application. The SPNEGO protocol is used to retrieve the Kerberos credentials from the browser. Web applications validate the credentials by checking them against the Key Distribution Center (KDC) server on the Windows domain server. If authentication succeeds, access is automatically granted to the Web applications.
Figure 21-1 below provides a conceptual view of the key components involved when using WNA. The authentication flow is described following the diagram.
The authentication flow is as follows:
(1) The user signs into their domain at the Windows desktop (Windows sign-on), which is configured for Kerberos authentication.
(2, 3, 4) The user then uses a browser to accesses the Web application, which is configured as a Java Single Sign-On (JSSO) partner application. If the user is not authenticated, they are redirected to JSSO. The JSSO application is configured with WNA authentication and uses the Generic Security Services Java API (GSS-API) token exchange protocol to request the user's Kerberos ticket. OC4J validates the ticket and extracts the user's Security Account Manager (SAM) account information.
(5, 6, 7) OC4J maps the SAM account name to the user in Active Directory by querying Active Directory to locate the user. Active Directory is then used to compute the user's enterprise groups. The user's identity and their enterprise groups are set as the authenticated subject to complete the authentication step. A cookie is then set for the user and the request is redirected back to the Web application.
The following tasks must be completed before configuring WNA:
Install OC4J server.
Verify that the Active Directory server that is being used is accessible and that the server's KDC is operational.
Create the necessary users and groups in Active Directory. For example oc4jadmin and the management groups such as oc4j-adminstrators and oc4j-app-adminstrators. Refer to "Creating Required Accounts in the LDAP Server" for a list of all required accounts.
The Linux host system where JSSO is deployed must be configured as a kerberos client.
To configure the Linux host system as a kerberos client:
On the Linux host server, open the /etc/krb5.conf file.
In the [libdefaults] section, edit the value of default_realm to a default kerberos realm name for your environment. The name can be a domain name and must be entered in upper case. For example:
[libdefaults] default_realm = MYDOMAIN.COM
In the [realms] section, replace the realm name with the name defined in step 2 and set its value to the fully qualified domain name of the Active Directory server including the kerberos port number. For example:
[realms]
MYDOMAIN.COM = {
kdc = name.mydomain.com:8787
}
In the [domain_realm] section, set the DNS domain name for your JSSO server equal to the default realm. For example:
[domain_realm].mydomain.com = MYDOMAIN.COM
Save and close the krb5.conf file.
Verify that the clocks on both your JSSO server and the Active Directory server are synchronized. This includes the time, date, and time zone settings.
A Web application host user account must be created on the Active Directory server with the same host name where JSSO is deployed.
To create a Web application service host user account:
Log in to the Active Directory server as the Administrator.
Click Start -> Programs -> Administrative Tools -> Active Directory Users and Computer.
Select the Users folder.
Click Create User.
Enter the following information:
First name: Enter a nickname that can be any readable name for this account.User logon name: Enter the JSSO host's complete DNS name. For example, mydomain.com.
Click Next.
Enter a password for this user. Do not select any password expiration settings.
Click Next. The new user appears in the list of users.
A keytab file is used by the Web application to map an account name to a service principal name. The keytab file is required and must be generated using the ktpass command.
To generate the keytab file for the Linux host:
Open a command prompt on the Active Directory server.
Issue the following command:
C:\> ktpass -princ HTTP/domain@DEFAULT_REALM -pass password -mapuser host_user_account -out file_name.keytab
Where:
The -princ (principal) value is HTTP/ followed by the fully qualified domain name of the Web application service host, followed by the default realm name. This is case sensitive. The Active Directory default realm must be in upper case and the fully qualified domain name of the Web application should be in lower case. For example:
-princ HTTP/name.mydomain.com@MYDOMAIN.COM
The -pass value must be set to the same password assigned to the Web application host user account created on the Active Directory server.
The -mapuser value is the JSSO fully qualified domain name (hostname) user created on the Active Directory server.
The -out value is the name for the output file. For example:
MyFile.keytab
Copy the generated keytab file to the OC4J instance where JSSO is deployed and configured on the Linux Host. For example:
ORACLE_HOME/j2ee/home/config
Issue the following kinit command to test the Kerberos connection between the Linux server and the Active Directory server to ensure that they have both been properly configured. The kinit executable for Red Hat Linux is located in the /usr/kerberos/bin directory.
# /usr/kerberos/bin/kinit -k -t ORACLE_HOME/j2ee/home/config/keytab_file HTTP/domain_name
The command must include the full path to the keytab file generated in step two and the fully qualified domain name of the of the Web application service host. For example:
# /usr/kerberos/bin/kinit -k -t oracle/j2ee/home/config/MyFile.keytab HTTP/name.mydomain.com
If the command is successful, there should be no output from the command and another command prompt returns. Any errors that are reported in the output must be resolved.
The tasks in this section configure an OC4J instance and its deployed Web applications to use WNA. Stop the OC4J instance before completing the tasks in this section. Make sure OC4J is started after completing the tasks in this section.
The following tasks are required to configure an OC4J instance to use WNA:
The following two system properties must be set to enable WNA for an OC4J instance. The properties are typically set within the oc4j.cmd, or oc4j.sh, script that is used to start OC4J. The properties can also be set on the command line when directly starting OC4J using oc4j.jar.
-Djavax.security.auth.useSubjectCredsOnly=false
-Doracle.security.jazn.config =ORACLE_HOME/j2ee/home/config/jazn.xml
System Properties for Debugging
Three additional properties can optionally be set to enable debug information for Kerberos authentication. The properties are:
-Djava.security.krb5.realm=kerberos-realm-name -Djava.security.krb5.kdc=kdc_host_name -Dsun.security.krb5.debug=true
Login modules for both Kerberos WNA and Active Directory must be added to the system-jazn-data.xml file. The login modules are added within the <jazn-loginconfig> element, which contains the login modules that are registered with OC4J.
To add Kerberos WNA and Active Directory login modules:
Open ORACLE_HOME/j2ee/home/config/system-jazn-data.xml.
Add the following XML block, which defines a kerberos login module configuration for the com.sun.security.jgss.accept application. The keytab and principal values must be the same as the values supplied in "Step 3: Generate and Test the Keytab File for the Linux Host". The keyTab value must include the complete path to keytab file and the principal value must be the fully qualified domain name (preceded by HTTP/) of the machine that is running the JSSO server.
...
<jazn-loginconfig>
<application>
<name>com.sun.security.jgss.accept</name>
<login-modules>
<login-module>
<class>com.sun.security.auth.module.Krb5LoginModule</class>
<control-flag>required</control-flag>
<options>
<option>
<name>debug</name>
<value>true</value>
</option>
<option>
<name>addAllRoles</name>
<value>true</value>
</option>
<option>
<name>useKeyTab</name>
<value>true</value>
</option>
<option>
<name>keyTab</name>
<value>C:/j2ee/home/config/MyFile.keytab</value>
</option>
<option>
<name>principal</name>
<value>HTTP/name.mydomain.com</value>
</option>
<option>
<name>doNotPrompt</name>
<value>true</value>
</option>
<option>
<name>storeKey</name>
<value>true</value>
</option>
</options>
</login-module>
</login-modules>
</application>
...
Add the following XML block, which configures the Active Directory login module configuration for the JSSO application. If you have already set the instance wide login module to be Active Directory, then you can skip this step.
<application> <name>javasso</name> <login-modules> <login-module> <class>oracle.security.jazn.login.module.LDAPLoginModule</class> <control-flag>required</control-flag> <options> <option> <name>oracle.security.jaas.ldap.connect.pool.prefsize</name> <value>10</value> </option> <option> <name>oracle.security.jaas.ldap.provider.connect.pool</name> <value>true</value> </option> <option> <name>oracle.security.jaas.ldap.provider.credential</name> <value>!welcome1</value> </option> <option> <name>oracle.security.jaas.ldap.provider.type</name> <value>Active Directory</value> </option> <option> <name>oracle.security.jaas.ldap.connect.pool.maxsize</name> <value>25</value> </option> <option> <name>oracle.security.jaas.ldap.role.searchscope</name> <value>subtree</value> </option> <option> <name>oracle.security.jaas.ldap.user.searchscope</name> <value>subtree</value> </option> <option> <name>oracle.security.jaas.ldap.membership.searchscope</name> <value>direct</value> </option> <option> <name>oracle.security.jaas.ldap.lm.cache_enabled</name> <value>true</value> </option> <option> <name>oracle.security.jaas.ldap.member.attribute</name> <value>member</value> </option> <option> <name>oracle.security.jaas.ldap.connect.pool.initsize</name> <value>2</value> </option> <option> <name>oracle.security.jaas.ldap.connect.pool.timeout</name> <value>300000</value> </option> <option> <name>oracle.security.jaas.ldap.user.object.class</name> <value>inetOrgPerson</value> </option> <option> <name>oracle.security.jaas.ldap.provider.url</name> <value>ldap://name.mydomain.com:389</value> </option> <option> <name>oracle.security.jaas.ldap.role.searchbase</name> <value>cn=builtin,dc=dlin,dc=net</value> </option> <option> <name>oracle.security.jaas.ldap.user.searchbase</name> <value>cn=users,dc=dlin,dc=net</value> </option> <option> <name>oracle.security.jaas.ldap.role.object.class</name> <value>group</value> </option> <option> <name>oracle.security.jaas.ldap.role.name.attribute</name> <value>cn</value> </option> <option> <name>oracle.security.jaas.ldap.user.name.attribute</name> <value>sAMAccountName</value> </option> <option> <name>oracle.security.jaas.ldap.provider.user</name> <value>cn=administrator,cn=users,dc=dlin,dc=net</value> </option> </options> </login-module> </login-modules> </application>
Add the following XML block, which defines a kerberos login module configuration for the JSSO application. The following values must be changed to match your Active Directory environment:
oracle.security.jaas.ldap.provider.user – the Active Directory server administrator
oracle.security.jaas.ldap.provider.credential – the Active Directory server administrator credential
oracle.security.jaas.ldap.user.searchbase – the Active Directory User Search Base
oracle.security.jaas.ldap.role.searchbase – the Active Directory Role Search Base
oracle.security.jaas.ldap.provider.url – the Active Directory server URL
...
<jazn-loginconfig>
<application>
<name>javasso</name>
<login-modules>
<login-module>
<class>oracle.security.jazn.login.module.LDAPLoginModule</class>
<control-flag>required</control-flag>
<options>
<option>
<name>oracle.security.jaas.ldap.connect.pool.prefsize</name>
<value>10</value>
</option>
<option>
<name>oracle.security.jaas.ldap.provider.connect.pool</name>
<value>true</value>
</option>
<option>
<name>oracle.security.jaas.ldap.provider.user</name>
<value>cn=administrator,cn=users,dc=dlin,dc=net</value>
</option>
<option>
<name>oracle.security.jaas.ldap.provider.credential</name>
<value>!welcome1</value>
</option>
<option>
<name>oracle.security.jaas.ldap.provider.type</name>
<value>Active Directory</value>
</option>
<option>
<name>oracle.security.jaas.ldap.connect.pool.maxsize</name>
<value>25</value>
</option>
<option>
<name>oracle.security.jaas.ldap.role.searchscope</name>
<value>subtree</value>
</option>
<option>
<name>oracle.security.jaas.ldap.user.searchscope</name>
<value>subtree</value>
</option>
<option>
<name>oracle.security.jaas.ldap.membership.searchscope</name>
<value>direct</value>
</option>
<option>
<name>oracle.security.jaas.ldap.lm.cache_enabled</name>
<value>true</value>
</option>
<option>
<name>oracle.security.jaas.ldap.member.attribute</name>
<value>member</value>
</option>
<option>
<name>oracle.security.jaas.ldap.connect.pool.initsize</name>
<value>2</value>
</option>
<option>
<name>oracle.security.jaas.ldap.connect.pool.timeout</name>
<value>300000</value>
</option>
<option>
<name>oracle.security.jaas.ldap.user.object.class</name>
<value>inetOrgPerson</value>
</option>
<option>
<name>oracle.security.jaas.ldap.provider.url</name>
<value>ldap://name.mydomain.com:389</value>
</option>
<option>
<name>oracle.security.jaas.ldap.role.searchbase</name>
<value>cn=builtin,dc=dlin,dc=net</value>
</option>
<option>
<name>oracle.security.jaas.ldap.user.searchbase</name>
<value>cn=users,dc=dlin,dc=net</value>
</option>
<option>
<name>oracle.security.jaas.ldap.role.object.class</name>
<value>group</value>
</option>
<option>
<name>oracle.security.jaas.ldap.role.name.attribute</name>
<value>cn</value>
</option>
<option>
<name>oracle.security.jaas.ldap.user.name.attribute</name>
<value>sAMAccountName</value>
</option>
</options>
</login-module>
</login-modules>
</application>
...
Save and close the system-jazn-data.xml file.
The JAZN configuration file must be edited to register the WNA authentication type. The file contains OC4J's JSSO configuration.
To register the WNA authentication type:
Open the ORACLE_HOME/j2ee/home/config/jazn.xml file.
Add the following property within the <jazn> element:
<jazn>
...
<property name="custom.sso.token.asserter.authtypes"
value="WINDOWS-KERBEROS-AUTH"/>
...
<jazn>
Save and close the file.
The Oracle application deployment descriptor for the JSSO application as well as any Web applications that uses JSSO must be edited in order to use WNA authentication.
To edit application deployment descriptors:
Open the ORACLE_HOME/j2ee/home/application-deployments/javasso/orion-application.xml file.
Comment-out the current <jazn> configuration.
Add the following <jazn> configuration and change the kerberos-servicename value to use to use the fully qualified domain name for your JSSO host (preceded by HTTP@):
<jazn provider="XML"> <jazn-web-app auth-method="WINDOWS_KERBEROS_AUTH"/> <property name="kerberos-servicename" value="HTTP@name.mydomain.com"/> </jazn>
Save and close the JSSO application's orion-application.xml file.
For each Web application that uses the JSSO application, open its orion-application.xml file and modify the XML provider's authentication method attribute to use CUSTOM_AUTH as follows:
<jazn provider="XML"> ... <jazn-web-app auth-method="CUSTOM_AUTH"/> ... </jazn>
The Oracle application deployment descriptor for an application is located in ORACLE_HOME/j2ee/home/application-deployments/application_name/orion-application.xml.
The host name where the JSSO application is deployed must be added as a trusted host within a client's Internet Explorer browser before attempting to access a Web application that has been configured to use WNA. If Internet Explorer is running on a computer that is in the JSSO domain, a Kerberos negotiation takes place. If Internet Explorer is running on a computer that is not part of the JSSO domain, then the fallback logic is to use basic authentication and the browser will prompt for a username and password. The username and password is authenticated against the Active Directory configured in the system-jazn-data.xml file.
To configure your browser settings and test the WNA feature, perform the following steps:
Log in to the Windows domain.
Open the Internet Explorer browser.
From the browser's Tools menu, select Internet Options. The Internet Options dialog box displays.
From the Internet Options dialog box, select the Security tab.
Click to highlight the Local intranet icon and click Sites. The Local intranet dialog box displays.
From the Local intranet dialog box, click Advanced.
In the text field, enter the URL for the computer that is hosting the JSSO server. For example, http://dude.mydomain.com. Do not include the JSSO login page or port number.
Click Add to add the URL to the list of Web sites for the Local intranet zone.
Click OK and then click OK again to close the Local intranet dialog box.
From the Security tab on the Internet Options dialog box, click Custom Level. The Security Settings dialog box displays. Make sure the Automatic logon only in Intranet zone option is selected.
Click OK to close the Security Settings dialog box.
Click OK to close the Internet Options dialog box.
In the browser address field, enter the following URL to navigate to the JSSO server login page: http://host:port/jsso/SSOLogin. Replace host:port with the host and port used to access the JSSO application.
The Kerberos credentials are transparently passed through the browser to the JSSO server and you are automatically logged into the JSSO server. If you are redirected to the top-level page, then the test is successful.
|
 Copyright © 2003, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|