20 Configuring Single Sign-On with Microsoft Clients
Overview of Single Sign-On with Microsoft Clients
Single sign-on (SSO) with Microsoft clients allows cross-platform authentication between Web applications or Web services running in a WebLogic domain and .NET Web service clients or browser clients (for example, Internet Explorer) in a Microsoft domain.
The Microsoft clients must use Windows Integrated Authentication based on the Simple and Protected Negotiate (SPNEGO) mechanism. Cross-platform authentication is achieved by emulating the negotiate behavior of native Windows-to-Windows authentication services that use the Kerberos protocol. In order for cross-platform authentication to work, non-Windows servers (in this case, WebLogic Server) need to parse SPNEGO tokens in order to extract Kerberos tokens which are then used for authentication.
Refer to the Microsoft documentation for details about Kerberos authentication support on Windows.
Note:
WebLogic Server's Single sign-on (SSO) support for Microsoft clients is available only for Web applications and not for other application types, such as EJBs.System Requirements for SSO with Microsoft Clients
To use SSO with Microsoft clients, you must meet both host computer requirements and client computer requirements.
Host Computer Requirements for Supporting SSO with Microsoft Clients
The host computer that supports SSO for Microsoft clients must meet the following system requirements:
-
A version of Microsoft Windows that is supported by WebLogic Server for SSO with Microsoft clients
For information about these supported versions, see Oracle Fusion Middleware Supported System Configurations.
-
Fully-configured Active Directory authentication service. Specific Active Directory requirements include:
-
User accounts for mapping Kerberos services
-
Service Principal Names (SPNs) for those accounts
-
Keytab files created and copied to the start-up directory in the WebLogic domain
-
-
WebLogic Server installed and configured properly to authenticate through Kerberos, as described in this chapter
Oracle recommends encrypting the user accounts that are mapped to Kerberos services on the WebLogic Server host. However, the ability to encrypt these accounts imposes additional requirements. The specific requirements depend on the encryption algorithm used, as shown in Table 20-1. For each encryption algorithm listed in Table 20-1, see the Oracle Fusion Middleware Supported System Configurations page for information about:
-
The corresponding version of Microsoft Windows that is supported as the Active Directory platform.
-
The specific versions of the Internet Explorer and Mozilla FireFox client types that are supported.
Table 20-1 Client Type Requirements for Using Encrypted User Accounts
Encryption Algorithm | Supported Client Type |
---|---|
DES |
|
AES-128, AES-256, and RC4 |
|
Footnote 1
User accounts accessed with a Java SE client can also be encrypted with DES, AES-128, AES-256, and RC4 and defined in Active Directory running on a Microsoft Windows platform supported by WebLogic Server for this purpose.
Client Computer Requirements for Supporting Microsoft Clients Using SSO
The computer hosting a Microsoft client that uses SSO must meet the following requirements:
-
An installation of Microsoft Windows
-
Include one of the client types listed in the following table, which also includes links to the instructions for configuring those clients:
Table 20-2 Configuration of Supported Hosted Clients
For the following client type . . . See the following topic . . . Internet ExplorerFoot 2
Mozilla FireFox Foot 2
.NET Framework with properly configured web service client
Standalone Java SE client application
Footnote 2
For information about the specific version supported for accessing user accounts that are defined in Active Directory and encrypted with AES-128, AES-256, or RC4, see Oracle Fusion Middleware Supported System Configurations.
Clients must be logged on to a Microsoft Windows domain and have Kerberos credentials acquired from the Active Directory server in the domain. Local logins are not supported.
Note:
For information about the versions of Microsoft Windows that are supported for hosting clients using SSO, and the encryption algorithms with which user accounts accessed by those clients can be defined in Active Directory, see Oracle Fusion Middleware Supported System Configurations.
Single Sign-On with Microsoft Clients: Main Steps
Configuring SSO with Microsoft clients requires set-up procedures in the Microsoft Active Directory, the client, and the WebLogic domain.
The procedure for configuring SSO with Microsoft client are detailed in the sections that follow.
-
Define a principal in Active Directory to represent the WebLogic Server. The Kerberos protocol uses the Active Directory server in the Microsoft domain to store the necessary security information.
-
Any Microsoft client you want to access in the Microsoft domain must be set up to use Windows Integrated Authentication, sending a Kerberos ticket when available.
-
In the security realm of the WebLogic domain, configure a Negotiate Identity Assertion provider. The Web application or Web service used in SSO needs to have authentication set in a specific manner. A JAAS login file that defines the location of the Kerberos identification for WebLogic Server must be created.
To configure SSO with Microsoft clients:
-
Configure your network domain to use Kerberos. See Configuring Your Network Domain to Use Kerberos.
-
Create a Kerberos identification for WebLogic Server.
-
Create a user account in the Active Directory for the host on which WebLogic Server is running.
-
Create a service principal name (SPN) for this account.
-
Create a user mapping and keytab file for this account.
-
-
Choose a Microsoft client (either a Web service or browser) or a Java SE client and configure it to use Windows Integrated Authentication. See Configuring Microsoft Clients to Use Windows Integrated Authentication.
-
Set up the WebLogic domain to use Kerberos authentication.
-
Create a JAAS login file that points to the Active Directory server in the Microsoft domain and the keytab file created in Step 1. See Creating a JAAS Login File.
-
Configure a Negotiate Identity Assertion provider in the WebLogic Server security realm. See Configuring a Negotiate Identity Assertion Provider.
-
-
Start WebLogic Server using specific start-up arguments. See Using Startup Arguments for Kerberos Authentication with WebLogic Server.
The following sections describe these steps in detail.
Configuring Your Network Domain to Use Kerberos
To configure Kerberos in your Windows domain controller, you need to configure each machine that will access the Key Distribution Center (KDC) to locate the Kerberos realm and available KDC servers.
A Windows domain controller can serve as the Kerberos Key Distribution Center (KDC) server for Kerberos-based client and host systems. On any domain controller, the Active Directory and the Kerberos services are running automatically.
Java GSS requires a Kerberos configuration file. The default name and location of the Kerberos configuration file depends on the operating system being used. Java GSS uses the following order to search for the default configuration file:
-
The file referenced by the Java property
java.security.krb5.conf
. -
${java.home}/lib/security/krb5.conf
. -
%windir%\krb5.ini
on Microsoft Windows platforms. -
/etc/krb5/krb5.conf
on Solaris platforms. -
/etc/krb5.conf
on other UNIX platforms.
For example:
Example 20-1 Sample krb5.ini File
[libdefaults] default_realm = EXAMPLE.COM (Identifies the default realm. Set its value to your Kerberos realm) default_tkt_enctypes = des-cbc-crc default_tgs_enctypes = des-cbc-crc ticket_lifetime = 600 [realms] EXAMPLE.COM = { kdc = <IP address for MachineA> (host running the KDC) (For UNIX systems, you need to specify port 88, as in <IP-address>:88) admin_server = MachineA default_domain = EXAMPLE.COM } [domain_realm] .example.com = EXAMPLE.COM [appdefaults] autologin = true forward = true forwardable = true encrypt = true
Creating a Kerberos Identification for WebLogic Server
Active Directory provides support for service principal names (SPN), which are a key component in Kerberos authentication. You must define an SPN to represent your WebLogic Server in the Kerberos realm. Learn how to create an SPN, user mapping, and keytab file for WebLogic Server.
SPNs are unique identifiers for services running on servers. Every service that uses Kerberos authentication needs to have an SPN set for it so that clients can identify the service on the network. An SPN usually looks something like name@YOUR.REALM
. If an SPN is not set for a service, clients have no way of locating that service. Without correctly set SPNs, Kerberos authentication is not possible. Keytab files are the mechanism for storing the SPNs. Keytab files are copied to the WebLogic domain and are used in the login process. This configuration step describes how to create an SPN, user mapping, and keytab file for WebLogic Server.
This configuration process requires the use of the following Active Directory utilities:
-
setspn
—Microsoft Windows Resource Kit -
ktpass
—Microsoft Windows distribution CD inProgram Files\Support Tools
Note:
The
setspn
andktpass
Active Directory utilities are products of Microsoft. Therefore, Oracle does not provide complete documentation for this utilities. See the appropriate Microsoft documentation for more information.
The process for creating a Kerberos identification consists of the following steps:
Step 1: Create a User Account for the Host Computer
In the Active Directory server, create a user account for the host computer on which WebLogic Server runs. (Select New > User, not New > Machine.)
When creating the user account, use a unique name to represent the host computer on which WebLogic Server runs. If your WebLogic Server instance runs on a host that is part of the Active Directory domain, then you must use a name other than the host name. For example, if the host is named myhost.example.com
, create a user in Active Directory called myweblogichost
. If your WebLogic Server instance runs on a machine that is not a part of the Active Directory domain, then you may use any unique name (including the host name) for creating the user account.
Note the password you defined when creating the user account. You will need it for the instructions described in Step 3: Define a Service Principal Name and Create a Keytab for the Service. Do not select the User must change password at next logon option or any other password options.
Step 2: Configure the User Account to Comply with Kerberos
Configure the new user account to comply with the Kerberos protocol as follows. The user account's encryption type must be DES, at a minimum, and the account must require Kerberos pre-authentication. Stronger encryption types are supported, including AES-128, AES-256, and RC4.
Note:
The use of a particular encryption type has a dependency on the version of the Microsoft Windows platform on which Active Directory runs. For more information, including a list of supported encryption types, see Oracle Fusion Middleware Supported System Configurations.
Note:
Setting the encryption type may corrupt the password. Therefore, reset the user password by right-clicking the name of the user account, selecting Reset Password, and re-entering the password created in Step 1: Create a User Account for the Host Computer.
Step 3: Define a Service Principal Name and Create a Keytab for the Service
As mentioned in Creating a Kerberos Identification for WebLogic Server, an SPN is a unique name that identifies an instance of a service and is associated with the logon account under which the service instance runs. The SPN is used in the process of mutual authentication between the client and the server hosting a particular service. The client finds a computer account based on the SPN of the service to which it is trying to connect. So, in a specific project, you need to link the service that will be invoked by your WebLogic clients to the account you just defined for your WebLogic Server. For example, the service invoked by the WebLogic browser clients is HTTP/myhost.example.com
, which needs to be linked to the myhost
account.
Windows account names are not multipart as Kerberos principal names. Because of this, it is not possible to directly create an account using the name HTTP/
hostname.dns.com
. Such a principal instance is created through SPN mappings. In this case, an account is created with a meaningful name hostname
, and an SPN mapping is added for HTTP/
hostname.dns.com
.
The specific steps for defining an SPN and creating a keytab for the service depend on the underlying platform on which WebLogic Server is running. They are provided in the following sections:
Defining an SPN and Creating a Keytab on Windows Systems
If WebLogic Server runs on a Windows system, complete the following steps:
Defining an SPN and Creating a Keytab on UNIX Systems
If WebLogic Server runs on a UNIX system, create a service principal name (SPN) and a keytab file for the HTTP service for the WebLogic Server account by using the ktpass
command-line tool. This tool enables an administrator to configure a non-Windows Server Kerberos service as a security principal in the Windows Server Active Directory.
The ktpass
command configures the SPN for the service in Active Directory and generates a Kerberos keytab file containing the shared secret key of the service. The tool allows UNIX-based services that support Kerberos authentication to use the interoperability features provided by the Windows Server Kerberos KDC service.
The ktpass
command has the following syntax:
ktpass -princ HTTP/hostname@REALM-NAME -mapuser account-name -pass password -out keytab-file-name -crypto algorithm -ptype KRB5_NT_PRINCIPAL
In the preceding syntax, algorithm
identifies the encryption algorithm to use. If you are using AES, specify AES128-SHA1
or AES256-SHA1
. For example:
ktpass -princ HTTP/myhost.example.com@EXAMPLE.COM -mapuser myhost -pass password -out mykeytab -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL
Note:
On UNIX systems, creating an SPN that uses a DES or an AES encryption algorithm is supported as of JDK 1.6.0_24 or later.
To verify that the SPN and the keytab file are set up correctly, you can do the following:
-
Use the
setspn -l
command to verify that the SPN is mapped successfully. -
Use the klist command to show
Key type: 17
for AES-128, andKey type: 18
for AES-256. For example:-klist -e -k keytab-file-name
-
Use the kinit command to verify that the Kerberos setup and keytab are valid.
Note:
The ktpass
command changes the principal name in the Active Directory server from account-name
to HTTP/
account-name
. Consequently, the keytab file is generated for a principal named HTTP/
account-name
. However, sometimes the name change does not happen. If not, you should change it manually in the Active Directory server; otherwise the keytab you generate will not work properly.
To modify the user logon name manually:
-
Right-click on the user node, select Properties, and click on the Account tab.
-
Export the generated keytab file to your UNIX machine hosting the WebLogic Server in the WebLogic domain directory.
Step 4: Verify Correct Setup
You can use the following utilities to verify that your SPN and keytab files are set up correctly.
-
Use the
setspn -l
command to verify that the SPN is mapped successfully. -
Use the
klist
command to verify the key type. For example:-klist -e -k keytab-file-name
For AES 128, this command displays
Key type: 17
. For AES 256,Key type: 18
is displayed. -
Use the
kinit
utility to verify that Kerberos is set up properly and that your principal and keytab are valid.The
kinit
utility is provided by the JRE and may be used to obtain and cache Kerberos ticket-granting tickets. You can run thekinit
utility by entering the following command:kinit -k -t keytab-file account-name
The output should appear similar to the following:
New ticket is stored in cache file C:\Documents and Settings\Username\krb5cc_myhost
Step 5: Update Default JDK Security Policy Files
AES-256 requires the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files, which are available at the following URL:
https://www.oracle.com/java/technologies/javase-jce-all-downloads.html
Note:
You can skip this step if you are running WebLogic Server on JDK 8u161 or later. On JDK 8u161 and later, stronger cryptographic algorithms are available by default.If you plan to use AES encryption, complete the following steps:
- Download JCE Unlimited Strength Jurisdiction Policy Files from the preceding URL.
- Uncompress and extract the jurisdiction policy files.
- Complete the installation procedure described in the included
README.txt
file.
Configuring Microsoft Clients to Use Windows Integrated Authentication
You must ensure that the Microsoft client you want to use for single sign-on is configured to use Windows Integrated Authentication. You can configure a .NET Web server, an Internet Explorer browser client, a Mozilla Firefox client, or a Java SE client to use Windows Integrated Authentication.
This section contains the following topics:
Note:
If the SPN for the user account on the WebLogic Server host to which the Kerberos ticket is mapped is configured to use DES or AES-256 encryption (see Step 2: Configure the User Account to Comply with Kerberos), the client must be running with a supported JDK. See Oracle Fusion Middleware Supported System Configurations.
Configuring a .NET Web Service
To configure a .NET Web service to use Windows Integrated Authentication:
Configuring an Internet Explorer Browser
To configure an Internet Explorer browser to use Windows Integrated Authentication, complete the procedures described in the following sections:
Configure Local Intranet Domains
In Internet Explorer:
- Select Tools > Internet Options.
- Select the Security tab.
- Select Local intranet and click Sites.
- In the Local intranet popup, ensure that the "Include all sites that bypass the proxy server" and "Include all local (intranet) sites not listed in other zones" options are checked.
- Click Advanced.
- In the Local intranet (Advanced) dialog box, add all relative domain names that will be used for WebLogic Server instances participating in the SSO configuration (for example,
myhost.example.com
) and click OK.
Configure Intranet Authentication
In Internet Explorer:
- Select Tools > Internet Options.
- Select the Security tab.
- Select Local intranet and click Custom Level... .
- In the Security Settings dialog box, scroll to the User Authentication section.
- Select Automatic logon only in Intranet zone. This option prevents users from having to re-enter logon credentials, which is a key piece to this solution.
- Click OK.
Verify the Proxy Settings
If you have a proxy server enabled:
- In Internet Explorer, select Tools > Internet Options.
- Select the Connections tab and click LAN Settings.
- Verify that the proxy server address and port number are correct.
- Click Advanced.
- In the Proxy Settings dialog box, ensure that all desired domain names are entered in the Exceptions field.
- Click OK to close the Proxy Settings dialog box.
Configuring a Mozilla Firefox Browser
To configure a Firefox browser to use Windows Integrated Authentication, complete the following steps:
Creating a JAAS Login File
If you are running WebLogic Server on either the Windows or UNIX platforms, you must create a JAAS login file. You must correctly specify the values of the userPrincipalName
attribute and the keytab
option in the JAAS login file.
The JAAS login file tells the WebLogic Security Framework to use Kerberos authentication and defines the location of the keytab file which contains Kerberos identification information for WebLogic Server. You specify the location of the JAAS login file in the java.security.auth.login.config
startup argument for WebLogic Server, as described in Using Startup Arguments for Kerberos Authentication with WebLogic Server.
Note:
The JAAS Login Entry names are com.sun.security.jgss.krb5.initiate
and com.sun.security.jgss.krb5.accept
.
The following example shows a sample JAAS login file for Kerberos authentication. Significant sections are shown in bold.
Example 20-2 Sample JAAS Login File for Kerberos Authentication
com.sun.security.jgss.krb5.initiate { com.sun.security.auth.module.Krb5LoginModule required principal="myhost@Example.CORP" useKeyTab="true" keyTab="mykeytab" storeKey="true"; }; com.sun.security.jgss.krb5.accept { com.sun.security.auth.module.Krb5LoginModule required principal="myhost@Example.CORP" useKeyTab="true" keyTab="mykeytab" storeKey="true"; };
For the principal option, specify the value of the userPrincipalName
attribute of the account under which the service is running. (Incorrectly specifying the user principal name results in an error such as "Unable to obtain password from user.")
The keytab file specified in the keytab
option must be accessible by the WebLogic Server process. Ensure that the appropriate permissions are set. If you are unsure of the search path WebLogic Server is using, provide the absolute path to the file. Make sure that you enclose the path in double quotes, and replace any backslash (\
) in the path with a double backslash (\\
) or a forward slash (/
).
Configuring the Identity Assertion Provider
The Negotiate Identity Assertion provider decodes Simple and Protected Negotiate (SPNEGO) tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users.
You need to configure a Negotiate Identity Assertion provider in your WebLogic security realm in order to enable SSO with Microsoft clients. See Configuring a Negotiate Identity Assertion Provider in this document, and also see Configure Authentication and Identity Assertion providers in the Oracle WebLogic Server Administration Console Online Help.
Using Startup Arguments for Kerberos Authentication with WebLogic Server
To use Kerberos authentication with WebLogic Server, use the following arguments in the Java command to start WebLogic Server:
-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=krb5Login.conf -Djava.security.krb5.realm=Example.CORP -Djava.security.krb5.kdc=ADhostname
In the preceding list of arguments:
-
javax.security.auth.useSubjectCredsOnly
specifies that it is permissible to use an authentication mechanism other than Subject credentials. -
java.security.auth.login.config
specifies the JAAS login file,krb5Login.conf
, described in Creating a JAAS Login File. -
java.security.krb5.realm
defines the Microsoft domain in which the Active Directory server runs. -
java.security.krb5.kdc
defines the host name on which the Active Directory server runs.
Java GSS messages are often very useful during troubleshooting, so you might want to add -Dsun.security.krb5.debug=true
as part of the initial setup.
Verifying Configuration of SSO with Microsoft Clients
To verify that SSO with Microsoft clients is configured properly, point a browser to the Microsoft Web application or Web service you want to use.
For the verification to work properly, the browser must be configured as described in Configuring an Internet Explorer Browser. If you are logged on to a Windows domain and have Kerberos credentials acquired from the Active Directory server in the domain, you should be able to access the Web application or Web service without providing a username or password.