Kerberos Single Sign-on

Overview

Oracle Enterprise Performance Management System products support Kerberos SSO if the application server that hosts EPM System products is set up for Kerberos authentication.

Kerberos is a trusted authentication service in which each Kerberos client trusts the identities of other Kerberos clients (users, network services, and so on) to be valid.

The following happens when a user accesses an EPM System product:

1. From a Windows computer, the user logs in to a Windows domain, which is also a Kerberos realm.
2. Using a browser that is configured to use Integrated Windows Authentication, the user tries to log into EPM System products running on the application server.
3. The application server (Negotiate Identity Asserter) intercepts the request and gets the Simple and Protected Generic Security Services API (GSSAPI) Negotiation Mechanism (SPNEGO) token with the Kerberos ticket from the browser's authorization header.
4. The asserter validates the user's identity included in the token against its identity store to pass information about the user to EPM System product. The EPM System product validates the user name against an Active Directory. The EPM System product issues an SSO token that supports SSO across all EPM System products.

Support Limitations

Kerberos SSO is supported for all EPM System products, with the following exceptions:

• Kerberos SSO is not supported for thick clients other than Oracle Smart View for Office.
• Smart View supports Kerberos integration for Oracle Essbase, Oracle Hyperion Planning, and Oracle Hyperion Financial Management providers only

Assumptions

This document, which contains application-level Kerberos configuration steps, assumes knowledge of Kerberos configuration at the system level. Before you start these procedures, confirm that the prerequisites for these tasks arecompleted.

This document assumes that you are working in a fully functional Kerberos-enabled network environment in which Windows client machines are configured for Kerberos authentication.

• The corporate Active Directory is configured for Kerberos authentication. See Microsoft Windows Server documentation.
• Browsers used to access EPM System products are configured to negotiate using Kerberos tickets.
• Time synchronization with no more than a five-minute skew between KDC and client machines. See "Authentication Errors are Caused by Unsynchronized Clocks" at http://technet.microsoft.com/en-us/library/cc780011(WS.10).aspx.

Kerberos SSO with WebLogic Server

Oracle WebLogic Server Kerberos SSO uses the Negotiate Identity Asserter to negotiate and decode SPNEGO tokens to enable SSO with Microsoft clients. WebLogic Server decodes SPNEGO tokens to obtain Kerberos ticket and validates and maps the ticket to a WebLogic Server user. You can use the Active Directory Authenticator of WebLogic Server with the Negotiate Identity Asserter to configure Active Directory as the user directory for WebLogic Server users.

When the browser requests access to an EPM System product, KDC issues a Kerberos ticket to the browser, which creates a SPNEGO token containing the supported GSS token types. The Negotiate Identity Asserter decodes the SPNEGO token and uses GSSAPIs to accept the security context. The identity of the user who initiated the request is mapped to a user name and passed back to WebLogic Server. Additionally, the WebLogic Server determines the groups to which the user belongs. At this stage, the requested EPM System product is made available to the user.

Note:

Users must use a browser that supports the SPNEGO (for example, Internet Explorer or Firefox) to access the EPM System products running on WebLogic Server.

Using the user ID derived from the authentication process, the EPM System product authorization process checks for provisioning data. Access to EPM System product is restricted based on provisioning data.

WebLogic Server Procedures to Support Kerberos Authentication

An administrator should complete these tasks to support Kerberos authentication:

• Create the WebLogic domain for EPM System. See Creating the WebLogic Domain for EPM System.
• Create an authentication provider. See Creating an LDAP Authentication Provider in WebLogic Server.
• Create a Negotiate Identity Asserter. See Creating a Negotiate Identity Asserter.
• Create a Kerberos identification. See Creating Kerberos Identification for WebLogic Server.
• Update the JVM options for Kerberos. See Updating JVM Options for Kerberos.
• Configure authorization policies. See Configuring Authorization Policies.
• Deploy and use SSODiag to verify that WebLogic Server is ready to support Kerberos SSO for EPM System. See Using SSODiag to Test the Kerberos Environment.

Creating the WebLogic Domain for EPM System

Generally, EPM System components are deployed into EPMSystem WebLogic domain (the default location is MIDDLEWARE_HOME/user_projects/domains/EPMSystem).

To configure the EPM System WebLogic domain for Kerberos authentication:

1. Install EPM System components.
2. Deploy Oracle Hyperion Foundation Services only.

   Foundation Services deployment creates the default EPM System WebLogic domain.

3. Log in to the Oracle Hyperion Shared Services Console to verify that Foundation Services deployment was successful. See Launching Shared Services Console.

Creating an LDAP Authentication Provider in WebLogic Server

A WebLogic Server administrator creates the LDAP Authentication provider, which stores user and group information in an external LDAP server. LDAP v2- or v3-compliant LDAP servers work with WebLogic Server. See these references:

• Configuring LDAP Authentication Providers in Oracle Fusion Middleware Securing Oracle WebLogic Server guide.
• Configure Authentication and Identity Assertion Providers in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

Creating a Negotiate Identity Asserter

The Negotiate Identity Assertion provider enables SSO with Microsoft clients. It decodes SPNEGO tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps the tokens to WebLogic users. The Negotiate Identity Assertion provider, an implementation of the Security Service Provider Interface (SSPI) as defined by the WebLogic Security Framework, provides the necessary logic to authenticate a client based on the client's SPNEGO token.

• Configuring a Negotiate Identity Assertion Provider in Oracle Fusion Middleware Securing Oracle WebLogic Server guide.
• Configure Authentication and Identity Assertion Providers in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

While creating the Negotiate Identity Assertion provider, set the JAAS Control Flag option to SUFFICIENT for all authenticators. See "Set the JAAS control flag" in Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

Creating Kerberos Identification for WebLogic Server

On the Active Directory domain controller machine, create user objects that represent WebLogic Server and EPM System web server, and map them to service principal names (SPN) that represent your WebLogic Server and web server in the Kerberos realm. Clients cannot locate a service that does not have an SPN. You store SPNs in keytab files that are copied to the WebLogic Server domain to be used in the login process.

See Creating identification for WebLogic Server in the Oracle Fusion Middleware Securing Oracle WebLogic Server guide for detailed procedures.

To create Kerberos identification for WebLogic Server:

1. On the Active Directory domain controller machine, create a user account; for example, epmHost, for the computer that hosts the WebLogic Server domain.

   Note:

   Create the identification as a user object, not as a machine.

   Use the simple name of the computer; for example, use epmHost if the host is named epmHost.example.com.

   Record the password you use while creating the user object. You will need it to create SPNs.

   Do not select any password options, especially the User must change password at next logon option.

2. Modify the user object to comply with the Kerberos protocol. The account must require Kerberos pre-authentication.
   • On the Account tab, select an encryption to use.
   • Ensure that no other account option (especially Do not require Kerberos pre-authentication) is selected.
   • Because setting the encryption type may have corrupted the object's password, reset the password to the password that you set while creating the object.
3. On the computer that hosts the Active Directory domain Controller, open a command prompt window and navigate to the directory where Active Directory support tools are installed.
4. Create and configure the required SPNs.
   1. Use a command similar to the following to verify that the SPNs are associated with the user object (epmHost) that you created in Step 1 of this procedure.

      setspn -L epmHost

   2. Using a command such as the following, configure the SPN for WebLogic Server in Active Directory Domain Services (AD DS) and generate a keytab file that contains the shared secret key.

      ktpass -princ HTTP/[e-mail] -pass password -mapuser epmHost -out c:\epmHost.keytab

5. Create a keytab file on the computer that hosts the WebLogic Server.
   1. Open a command prompt.
   2. Navigate to MIDDLEWARE_HOME/jdk/bin.
   3. Execute a command such as the following:

      ktab -k keytab_filename -a [e-mail]

   4. When prompted for a password, enter the password that you set while creating the user in step 1 of this procedure.
6. Copy the keytab file into the startup directory within the WebLogic domain; for example, into C:\Oracle\Middleware\user_projects\domains\EPMSystem.
7. Verify that Kerberos authentication is working correctly.

   kinit -k -t keytab-file account-name

   In this command, account-name indicates the Kerberos principal; for example, HTTP/[e-mail]. The output from this command should be similar to the following:

   New ticket is stored in cache file C:\Documents and Settings\Username\krb5cc_MachineB

Updating JVM Options for Kerberos

See Using Startup Arguments for Kerberos Authentication with WebLogic Server and Creating a JAAS Login File in Oracle Fusion Middleware Securing Oracle WebLogic Server 12c Release (12.2.1.4).

If EPM System managed servers are run as Windows services, update the Windows registry to set the JVM startup options.

To update JVM Startup options in Windows registry:

1. Open Windows Registry Editor.
2. Select My Computer, then HKEY_LOCAL_MACHINE, then Software, then Hyperion Solutions, then Foundationservices0, and then HyS9EPMServer_epmsystem1.
3. Create the following string values:

   Note:

   The names listed in the following table are examples.

   Table 3-3 JVM Startup Options for Kerberos Authentication

   Name	Type	Data
   JVMOption44	REG_SZ	-Djava.security.krb5.realm=Active Directory Realm Name
   JVMOption45	REG_SZ	-Djava.security.krb5.kdc=Active Directory host name or IP address
   JVMOption46	REG_SZ	-Djava.security.auth.login.config=location of Kerberos login configuration file
   JVMOption47	REG_SZ	-Djavax.security.auth.useSubjectCredsOnly=false

4. Update the value of JVMOptionCount DWord to reflect the added JVMOptions (add 4 to the current decimal value).

Configuring Authorization Policies

See Options for Securing Web Application and EJB Resources in the Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle WebLogic Server guide for information on configuring authorization policies for Active Directory users who access the EPM System.

For sample policy configuration steps, see Creating Policies for SSODiag.

Using SSODiag to Test the Kerberos Environment

SSODiag is a diagnostic web application that tests whether the WebLogic Server in your Kerberos environment is ready to support EPM System.

Deploying SSODiag

Use the WebLogic Server administrator credentials (default user name is epm_admin) that you specified while deploying Foundation Services to deploy SSODiag.

To deploy and configure SSOdiag:

1. Log on to the WebLogic Server Administration Console for EPM System domain.

2. In Change Center, select Lock & Edit

3. From EPMSystem in Domain Structure, click Deployments.
4. In Summary of Deployments, click Install.
5. In Path, select EPM_ORACLE_HOME/products/Foundation/AppServer/InstallableApps/common/SSODiag.war.
6. Click Next.
7. In Choose targeting style, ensure that Install this deployment as an application is selected, and then click Next.
   
   
8. In Select Deployment Targets, select the following, and then click Next.
   • EPMServer
   • All servers in the cluster
     
     
9. In Optional Settings, select Custom Roles and Policies: Use only roles and Policies that are defined in the Administration Console as the security model.
   
   
10. Click Next.
11. On the review screen, select No, I will review the configuration later.
12. Click Finish.
13. In Change Center, select Activate Changes.

Configuring Oracle HTTP Server for SSODiag

Update mod_wl_ohs.conf to configure Oracle HTTP Server to forward SSODiag URL requests to the WebLogic Server.

To configure URL forwarding in Oracle HTTP Server:

1. Using a text editor, open EPM_ORACLE_INSTANCE/httpConfig/ohs/config/fmwconfig/components/OHS/ohs_component/mod_wl_ohs.conf.
2. Add a LocationMatch definition for SSODiag:

   <LocationMatch /SSODiag/>
       SetHandler weblogic-handler
       WeblogicCluster myServer:28080
   </LocationMatch>

   In the preceding sample, myServer denotes the Foundation Services host machine, and 28080 represents the port at which Oracle Hyperion Shared Services listens for requests.

3. Save and close mod_wl_ohs.conf.
4. Restart Oracle HTTP Server.

Creating Policies for SSODiag

Create a policy in the WebLogic Server Administrative Console to protect the following SSODiag URL.

http://OHS_HOST_NAME:PORT/SSODiag/krbssodiag

In this sample, OHS_HOST_NAME indicates the name of the server that hosts Oracle HTTP Server and PORT indicates the port where Oracle HTTP Server listens for requests.

To create policies to protect SSODiag:

1. In the Change Center in WebLogic Server Administration Console for EPM System domain, select Lock & Edit.
2. Select Deployments, then SSODiag, then Security, then URLPatterns and then Policies.
3. Create the following URL patterns:
   • /
   • /index.jsp
4. Modify each URL pattern that you created:
   1. From the list of URL patterns in Stand-Alone Web Application URL Patterns, open the pattern (/) that you created by clicking it.
   2. Select Add Conditions.
   3. In Predicate List, select User.
   4. Select Next.
   5. In User Argument Name, enter the Active Directory user whose account is used to access a client desktop configured for Kerberos authentication; for example, krbuser1, and select Add. krbuser1 is an Active Directory or Windows desktop user.
   6. Select Finish.

5. Select Save.

Using SSODiag to Test WebLogic Server Configuration for Kerberos Authentication

If WebLogic Server configuration for Kerberos authentication works correctly, the Oracle Hyperion Kerberos SSO diagnostic Utility V 1.0 page displays the following message:

Retrieving Kerberos User principal name... Success.
Kerberos principal name retrieved... SOME_USER_NAME

Caution:

Do not configure EPM System components for Kerberos authentication if SSODiag cannot retrieve the Kerberos principal name.

To test WebLogic Server configuration for Kerberos authentication:

1. Start Foundation Services and Oracle HTTP Server.
2. Using WebLogic Server Administration Console, start the SSODiag web application to service all requests.
3. Log on to a client machine configured for Kerberos authentication using valid Active Directory credentials.
4. Using a browser, connect to the following SSODiag URL:

   http://OHS_HOST_NAME:PORT/SSODiag/krbssodiag

   In this sample, OHS_HOST_NAME indicates the name of the server that hosts Oracle HTTP Server, and PORT indicates the port where Oracle HTTP Server listens for requests.

   If Kerberos authentication works properly, SSODiag displays the following information:

   Retrieving Kerberos User principal name... Success.
   Kerberos principal name retrieved... SOME_USER_NAME

   If Kerberos authentication does not work properly, SSODiag displays the following information:

   Retrieving Kerberos User principal name... failed.
   

Changing the Security Model

The default security model for web applications secured by the security realm is DDonly. You must change the security model to CustomRolesAndPolicies.

To change the security model:

1. Using a text editor, open MIDDLEWARE_HOME/user_projects/domains/EPMSystem/config/config.xml.
2. Locate the following element in the application deployment descriptor for each Foundation Services component:

   <security-dd-model>DDOnly</security-dd-model>

3. Change the security model as follows for each component:

   <security-dd-model>CustomRolesAndPolicies</security-dd-model>

4. Save and close config.xml.

Updating EPM System Security Configuration

Change EPM System security configuration to enable Kerberos SSO.

To configure EPM System for Kerberos authentication:

1. Log on to Shared Services Console as administrator.
2. Add the Active Directory domain that is configured for Kerberos authentication as an external user directory in Shared Services. See "Configuring OID, , and Other LDAP-based User Directories" in the Oracle Enterprise Performance Management System User Security Administration Guide.
3. Enable SSO. See Configuring OID, Active Directory, and Other LDAP-based User Directories.

   In Security Options, select the settings in the following table to enable Kerberos SSO.

   Table 3-4 Settings to Enable Kerberos SSO

   Field	Required Setting
   Enable SSO	Selected
   SSO Provider or Agent	Other
   SSO Mechanism	Get Remote User from HTTP Request

4. Restart Foundation Services.

Testing Kerberos SSO

Log in to Foundation Services to verify that Kerberos SSO is working properly.

To test Kerberos SSO:

1. Verify that Foundation Services and Oracle HTTP Server are running.
2. Log on to a client machine configured for Kerberos authentication using a valid Active Directory credentials.
3. Using a browser, connect to the Foundation Services URL.

Configuring EPM System Components

Using EPM System Configurator, configure and deploy other EPM System components into the WebLogic domain where Foundation Services is deployed.

Configuring EPM System Managed Servers for Kerberos Authentication

In Microsoft Windows environments, EPM System managed servers are run as Windows services. You must modify the startup JVM options for each WebLogic managed server. A comprehensive list of managed servers in noncompact deployment mode:

• AnalyticProviderServices0
• CalcMgr0
• ErpIntegrator0
• EssbaseAdminServer0
• FinancialReporting0
• HFMWeb0
• FoundationServices0
• HpsAlerter0
• HpsWebReports0
• Planning0
• Profitability0

If EPM System web applications are deployed in the compact deployment mode, you need to update the startup JVM options of EPMSystem0 managed server only. If you have multiple compact managed servers, you must update the startup JVM options for all managed servers.

See Using Startup Arguments for Kerberos Authentication with WebLogic Server in the Oracle Fusion Middleware Securing Oracle WebLogic Server guide.

Note:

The following procedure describes how to set the startup JVM options for the FoundationServices managed server. You must perform this task for each WebLogic managed server in the deployment.

For detailed procedures to configure JVM options in WebLogic Server startup scripts, see Updating JVM Options for Kerberos.

To configure JVM options in WebLogic Server startup scripts

Configuring Authorization Policies

Configure authorization policies for Active Directory users who will access EPM System components other than Foundation Services. See Configuring Authorization Policies for information on configuring security policies from WebLogic Administration Console.

Changing Default Security Model of EPM System Components

You edit the EPM System configuration file to change the default security model. For non-compact EPM System deployments, you must change the default security model of each EPM System web application recorded in config.xml. A list of EPM System web applications:

• AIF
• APS
• CALC
• EAS
• FINANCIALREPORTING
• PLANNING
• PROFITABILITY
• SHAREDSERVICES
• WORKSPACE

To change the security model:

1. Using a text editor, open MIDDLEWARE_HOME/user_projects/domains/EPMSystem/config/config.xml
2. In the app-deployment definition of each EPM System component, set the value of <security-dd-model> to CustomRolesAndPolicies as shown in the following example:

   <app-deployment>
      <name>SHAREDSERVICES#11.1.2.0</name>
      <target>EPMServer</target>
      <module-type>ear</module-type>
      <source-path>C:\Oracle\Middleware\EPMSystem11R1/products/Foundation/AppServer/InstallableApps/common/interop.ear</source-path>
      <security-dd-model>CustomRolesAndPolicies</security-dd-model>
      <staging-mode>nostage</staging-mode>
   </app-deployment>

3. Save and close config.xml.
4. Restart the WebLogic Server.

Creating URL Protection Policies for EPM System Components

Create a URL protection policy in the WebLogic Server Administrative Console to protect each EPM System component URL. See Options for Securing Web Applications and EJB Resources in the Oracle Fusion Middleware Securing Resources Using Roles and Policies for Oracle WebLogic Server guide for details.

To create URL protection policies:

1. In the Change Center in WebLogic Server Administration Console for EPM System domain, click Lock & Edit.
2. Click Deployments.
3. Expand an EPM System enterprise application (for example PLANNING) in your deployment and then click its web application (for example HyperionPlanning). See Changing Default Security Model of EPM System Components for a list of EPM System components.

   Note:

   Some enterprise applications; for example Oracle Essbase Administration Services, comprise multiple web applications for which URL patters must be defined.
4. Create a URL Pattern scoped policy for the web application.
   • AIF
   • APS
   • CALC
   • EAS
   • FINANCIALREPORTING
   • PLANNING
   • PROFITABILITY
   • SHAREDSERVICES
   • WORKSPACE
   1. Click Security, then Policies, and then New.
   2. In URL Pattern, enter the protected and unprotected URLs for the EPM System products. See Protecting and Unprotecting EPM System Resources for more details.
   3. Click OK.
   4. Click the URL pattern that you created.
   5. Click Add Conditions.
   6. In Predicate List, select a policy condition, and then click Next.

      Oracle recommends that you use the Group condition, which grants this security policy to all members of a specified group.

   7. Specify the arguments that pertain to the predicate you chose. For example, if you chose Group in the preceding step, you should complete the following steps:
   8. In Group Argument Name, enter the name of the group that contains the users who should be allowed to access the web application. The name that you enter must exactly match an Active Directory group name.
      • Click Add.
      • Repeat the preceding steps to add more groups.
   9. Click Finish.

      WebLogic Server displays an error message if it cannot locate the group in Active Directory. You must resolve this error before before proceeding.

   10. Select Save.
5. Repeat Step 3 and Step 4 of this procedure for the other EPM System components in your deployment.
6. In the Change Center, click Release Configuration.
7. Restart WebLogic Server.

Enable Client Certificate-Based Authentication in Web Applications

Insert login-config definition in the configuration file of the following application archives located within EPM_ORACLE_HOME/products/.

• Essbase/eas/server/AppServer/InstallableApps/Common/eas.ear
• FinancialDataQuality/AppServer/InstallableApps/aif.ear
• financialreporting/InstallableApps/HReports.ear
• Profitability/AppServer/InstallableApps/common/profitability.ear

To enable client certificate-based authentication:

1. Stop EPM System components and Processes.
2. Using 7 Zip, expand a web archive contained within the enterprise archive; for example,EPM_ORACLE_HOME/products/Essbase/eas/server/AppServer/InstallableApps/Common/eas.ear/eas.war.
3. Navigate to WEB-INF.
4. Modify web.xml by adding the following login_config definition immediately before the </webapp> element:

   <login-config>
        <auth-method>CLIENT-CERT</auth-method>
   </login-config>

5. Save web.xml.
6. Click Yes when 7 Zip queries whether you want to update the archive.

Updating EPM System Security Configuration

Configure EPM System security to honor SSO. See Configuring EPM System for SSO.