46 Configuring Access Manager for Windows Native Authentication

Access Manager enables Microsoft Internet Explorer users to automatically authenticate to their Web-based single sign-on applications using their desktop credentials. This is known as Windows Native Authentication (WNA)

This chapter contains the following sections to describe how to prepare your environment and perform this integration using Active Directory:

46.1 Introducing Access Manager with Windows Native Authentication

Access Manager supports Active Directory Multi-Domain and Multi-Forest topology integration with Windows Native Authentication (WNA).

The Active Directory directory service uses a data store that is also known as the directory for information about objects, such as users, groups, computers, domains, organizational units, and security policies.

See Also:

The System Requirements and Supported Platforms for Oracle Identity and Access Management 11gR1 at https://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html

For the integration, an application must be protected by an Access Manager authentication policy that uses the Kerberos authentication scheme (KerberosScheme) with WNA as the Challenge Method with the KerberosPlugin Authentication Module. In this case, credentials must be stored in a Windows Active Directory instance that is registered as a user-identify store with Access Manager.

Each protected resource is defined in an Application Domain. The Authentication Policy includes the Authentication Scheme (KerberosScheme) that uses an Authentication Module (Kerberos) that is tied to the default User Identity Store. The store uses the value of "User Name Attribute" for authentication. This value is tied to the user in Active Directory and its values for userprincipalname = username@domian or SamAccountName = username, depending on the specific Access Manager release.

When Access Manager single sign-on is combined with WNA, a Kerberos session ticket is generated that contains the user's login credentials (among other things). This Kerberos session ticket is not visible to the user.

Access Manager interoperates with WNA, which uses Kerberos credentials obtained when the user logs in to a Windows Domain. This cross-platform authentication is achieved by emulating the negotiate behavior of native Windows-to-Windows authentication services that use the Kerberos protocol. For this cross-platform authentication to work, OAM Servers must parse SPNEGO tokens to extract the Kerberos tokens that are then used for authentication.

  • SPNEGO is a Generic Security Services Application Programming Interface (GSSAPI) "pseudo mechanism" used to negotiate one of a number of possible real mechanisms. SPNEGO is largely employed in the Microsoft "HTTP Negotiate" authentication extension which uses it to allow initiators and acceptors to negotiate either Kerberos or NTLMSSP mechanisms. GSSAPI implementation is included with most major Kerberos distributions.

    See http://tools.ietf.org/html/rfc4559 for more information on SPNEGO.

  • Kerberos is a network authentication protocol that provides strong authentication for client/server applications and services using a secret-key cryptography. A free implementation of Kerberos protocol is available from the Massachusetts Institute of Technology and is also commercially available.

See:

46.1.1 Understanding Access Manager WNA Login and Fall Back Authentication

With WNA implemented, a user can open a Web application without another challenge for credentials because the Kerberos session ticket is passed through the browser to the OAM Server.

The OAM Server decrypts the received token (using keytab) and derives the authenticated user name from it. If authentication succeeds the user is granted access to the Web application automatically.

See Also:

Supported browsers in the System Requirements and Supported Platforms for Oracle Identity and Access Management 11gR1 at https://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html

The following sections describe an overview of the process of two WNA login scenarios.

46.1.1.1 Successful Access Manager WNA Authentication
  1. The Browser is configured for Integrated Windows Authentication (IWA).

    This is a browser security configuration. If the browser being used is not configured to use IWA, no TGT is supplied when a resource protected by the Kerberos authentication module is requested. A browser basic authentication window is displayed where you can enter a valid username/password combination defined in the Default Identity Store for User login attribute.

  2. A resource protected by Access Manager and WNA is called.

    The protected resource should be configured as an intranet resource. This is done by adding the site in the "Local Intranet" zone of the Browser configuration.

  3. A valid Kerberos ticket is present - Http headers... Authorization: Negotiate YIIJ/...

  4. The user is not challenged for authentication.The requested resource is displayed, proving that WNA works.

In other words, when the browser is configured to use Integrated Windows Authentication, and a resource is protected by the Kerberos authentication module, then:

  • If a Kerberos ticket is received by Access Manager (regardless of the domain), authentication is attempted:

    • Successful: Access is granted.

    • Failure: An incorrect user name or password error occurs if information from the Kerberos ticket is either not present or does not match the value of the User Name Attribute defined in the Default User Identity Store. Access is denied. The browser automatically submits the ticket, and the interaction with Access Manager is repeated until the user has been locked out. The browser cannot be made to pause before the start of each exchange.

  • If the user is not logged on to a Windows Domain by way of Kerberos authentication, the browser sends OAM an NTLM token for authentication instead of a Kerberos token. Depending on how Access Manager is configured, it either uses WNA Fallback Authentication upon receiving an NTLM token or authentication fails.

    Note:

    You need to configure Access Manager to provide fallback authentication when the browser sends an NTLM token. Without configuration, authentication fails. For configuration steps, see Configuring WNA for NTLM Fallback.

    NTLMSSP is a security support provider that is available on all versions of the Distributed Component Object Model (DCOM). It uses the NTLM protocol for authentication, which does not actually transmit the user's password to the server during authentication.

Note:

If a Kerberos ticket cannot be identified by Access Manager (regardless of browser, Operating System, domain-login, and so on), the fallback mechanism is invoked.

46.1.1.2 Access Manager WNA Fallback Authentication

Fallback uses the authentication scheme "BasicScheme" with a challenge method of "Basic" and authentication module "LDAP".

This LDAP Authentication Module uses the LDAP plug-in. In this plug-in, the User Identity Store can be defined as any currently registered User Identity Store in which you define the attribute to be used for "User Name Attribute." The authentication module can be changed using the console.

  1. The Browser is configured for Integrated Windows Authentication (IWA).

    This is a browser security configuration. Access Manager handles two types of WNA fallback authentication.

    • Within Domain where IWA is enabled: OAM supports WNA for the SPNEGO token. But sometimes due to configuration or other issues, OAM receives NTLM tokens from the client rather than SPNEGO. During the DEFAULT flow, OAM will try to authenticate using the NTLM token and fail because OAM doesn't have the capability to authenticate NTLM tokens. Thus, with introduction of "HandleNTLMResponse" configuration, OAM server will challenge client with Basic prompt for authentication. i.e. The fallback here is to prompt for basic mode of authentication if client is sending NTLM tokens to OAM Server. See Configuring WNA for NTLM Fallback for details.

    • Outside Domain where IWA is disabled: Here no extra configuration is needed. By default the OOTB user will see a BASIC prompt during authentication.

  2. A resource protected by Access Manager and WNA is called.

    The protected resource should be configured as an intranet resource. This is done by adding the site in the "Local Intranet" zone of the Browser configuration.

  3. No ticket is present (NTLM/Kerberos) - Http headers... Authorization: Basic

  4. A basic authentication window pops up.

  5. The user enters a valid username/password.

  6. The requested resource is displayed (WNA Fallback works).

46.1.2 Supported Kerberos Authentication Modules

Use the Kerberos Authentication Module or KerberosPlugin Authentication Module when configuring Access Manager for Windows Native Authentication. The Kerberos Authentication Module identifies the key tab file and krb5 configuration file names and Principal.

The KerberosPlugin Authentication Module relies on bundled plug-ins (or those that are developed using the Access Manager Authentication Extensibility Java API). This module uses more than one plug-in that you can orchestrate to ensure that each one performs a specific authentication function. The KerberosPlugin Authentication Module is more robust and richer in functionality than the Kerberos Authentication Module. The KerberosPlugin Authentication Module (along with a plain WNA configuration) supports the following approaches:

  • Kerberos Plugin with Oracle Virtual Directory: Using Access Manager with orchestrated authentication plug-ins integrated with Oracle Virtual Directory virtualize multiple Active Directory Global Catalogs.

  • Kerberos Plugin with Search Failover Across Multiple ADGCs: Using Access Manager with orchestrated authentication plug-ins that exercise a failover pattern across multiple Active Directory Global Catalogs.

46.2 About Preparing Your Active Directory and Kerberos Topology

You need a fully-configured Microsoft Active Directory authentication service set up. Your Active Directory and Kerberos client will operate together.

The tasks in this section are required regardless of the approach you choose. However, none of this is Oracle specific.

Note:

The following sample scenario represents a typical Active Directory topology, and is not a requirement dictated by or for Access Manager. The naming used here is an example only. Your environment will be different.

As a sample scenario, consider two Active Directory forests operating within a company.

Forest Domain Name

ORACLE

lm.example.com

SPRITE

lmsib.sprite.com

Consider that a child domain exists within the ORACLE forest: child.lm.example.com.

Trust is required as follows:

  • Between forests: Two-way, non-transitive trust.

  • Between the child domain and its parent: Two-way, transitive trust.

The suffixes and inheritance are:

  • SPRITE users have UPN suffixes such as sun.com orjava.com. The SPRITE forest contains testuser.java.com.

  • ORACLE users have suffixes such as myoracleco.com and oracleco.com. The ORACLE forest contains testuser.oracleco.com.

  • ORACLE child domain inherits the UPN suffixes of the parent domain.

Note:

Pre-Windows user names formed as DOMAIN\USERNAME, are not supported.

For integration with WNA, the User Name Attribute defined for the Default Identity Store can be any attribute whose value matches the Active Directory user's samAccountName.

You also need to know which encryption type your environment will use. In some cases a user might be created with "Use DES encryption types for this account" enabled. However, Active Directory is not using DES encryption.

Note:

The keytab file created in the following procedure uses RC4-HMAC encryption.

Access Manager supports what JGSS/JDK6 supports. The limitation on the TGT encryption that can be used would be determined by the piece that is the least common or lowest encryption supported: KDC, Keytab, Operating System, Kerberos client. Access Manager does not support any specific Kerberos encryption type. It is dependent on the Generic Security Services (GSS)/Kerberos jdk encryption types with which it is certified. Access Manager is not dependent on any encryption type and does not use TGT encryption. As part of SPNEGO token Access Manager only looks into the Service Ticket which is encrypted with a key that the service (in this case Access Manager) has registered when executing the ktpass/keytab commands.

Note:

The keytab file created in the following procedure uses RC4-HMAC encryption.

Encryptions are used for communication among the different OS (Windows/Linux acting as Kerberos Server/Client). OAM Server just needs the SPNEGO token, from which it extracts the user credential. The encryption used in this three way negation process between the Windows Client (Browser), the Windows KDC, and the Generic Security Services (GSS) classes used by Access Manager, depend on the versions used (which must match).

See Also:

My Oracle Support for details about the Kerberos Encryption types Access Manager Supports [Doc 1212906.1] at: https://support.oracle.com/CSP/main/article?cmd=show&type=NOT&id=1212906.1

In the trusted domain (for example, the root domain lm.example.com), it is required that you follow the steps provided to:

  • Create an account for the OAM Server.

  • Extract the keytab file that was configured with the Active Directory Multi-Domain or Multi-Forest topology and trust relationships.

  • Specify the Service Principal Name (SPN) using the fully-qualified hostname of the OAM Server (or the load balancer that represents the OAM Cluster), followed by the Realm name.

For this example the names in Table 46-1 are used.

Table 46-1 Sample Naming

Name Description

kdc.lm.example.com

KDC hostname

KDC is a trusted network service that supplies session tickets and temporary session keys to users and computers within an Active Directory domain. The KDC runs on each domain controller as part of Active Directory Domain Services and is implemented as a domain service. The KDC uses Active Directory as its account database. In implementations of the Kerberos protocol, the KDC is a single process that provides two services: Authentication Service (AS) and Ticket Granting Service (TGS).

kdc.lm.example.com

AdminServer hostname

This is the same as the KDC hostname.

oam11g.example.com

OAM Server hostname

LM.EXAMPLE.COM

LMSIB.SPRITE.COM

Default Active Directory Realm

Second Active Directory Realm

The realm name identifies the location of the user account. A realm name can be either a prefix or a suffix.

When an access client sends user credentials, a user name is often included. Within the user name are two elements: a user account name and user account location.

HTTP/fully_qualified_OAMServerhostname@REALM_NAME (in CAPITAL letters

Service Principal Names (SPNs) are needed for user accounts (the name by which a client uniquely identifies an instance of a service).

Note: If you install multiple instances of a service on computers throughout a forest, each instance must have its own Service Principal Name.

46.2.1 Preparing Active Directory and Kerberos

You can prepare Active Directory and Kerberos.

Commands are for a Unix Operating System. Command syntax will vary depending on the specific Operating System in your environment.

  1. Check the Oracle certification matrix to ensure you are installing a supported version of Active Directory for this integration:

    https://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html
    
  2. Install and configure Active Directory as follows:

    • Multi-Forest topology with requisite trust relationships configured and functional, including:

      a. User accounts to map Kerberos services

      b. Service Principal Names (SPNs) for these user accounts (the name by which a client uniquely identifies an instance of a service).

      c. Key tab files

    • Active Directory Global Catalog (ADGC) enabled and functional within each forest

    • Multi-Forest Deployment: In this case, ensure there exists a naming attribute (available in global catalog) that uniquely identifies the users originating from various forests. Generally, userprincipalname is unique for the forest and samAccountName is unique for the domain

    • One domain that is directly or indirectly trusted by every other domain, regardless of forest affiliation.

  3. Create a user for Access Manager use during WNA authentication and record this user name for generating the keytab file (no DES encryption).

  4. Record the OAM Server hostname. For example:

    oam11g.example.com
    
  5. Record the KDC hostname and the Active Directory domain/realm:

    KDC = kdc.lm.example.com
    Default AD Realm = lm.example.com
    
  6. Create the Service Principal Name (SPN) of the Active Directory user that the OAM Server client is using, and record the results (including encryption type).

    The user name should be in the format user_name@example.com where example.com is the domain name of the Active Directory. For example:

    ktpass -princ <protocol/oamserver_host> -pass <mypassword> -mapuser <user from step 3> -out <path_to_filename>

    Note:

    Ensure that the case of the user name is consistent when entering it with the ktpass, kinit and klist commands. If you enter the user name in lower case when running one command, it must be entered in lower case when running the other commands.

    For example, the case used in the commands to create the keytabs and the configuration in /etc/krb5.conf file need to match. When ktpass is run to create the keytab (as below), the host name of the KDC server is lm.example.com. Since this is all lower case, the configuration in the /etc/krb5.conf file must also be lower case. Case sensitivity is not the issue as long as the case matches.

    ktpass -princ HTTP/oam11g.example.com@lm.example.com -mapuser oam -pass 
    examplepw -out c:\temp\oam.keytab
    
    C:\Users\Administrator>ktpass -princ HTTP/oam11g.example.com@LM.EXAMPLE.COM
    -mapuser oam -pass welcome1 -out c:\temp\oam.keytab
    Targeting domain controller: kdc.lm.example.com
    Using legacy password setting method
    Successfully mapped HTTP/oam11g.example.com to oam.
    WARNING: pType and account type do not match. This might cause problems.
    Key created.
    Output keytab to c:\temp\oam.keytab:
    Keytab version: 0x502
    keysize 80 HTTP/oam11g.example.com@lm.example.com ptype 0 (KRB5_NT_
    UNKNOWN) vno 3 etype 0x17 (RC4-HMAC) keylength 16 (0xa3a685f89364d4a
    5182b028fbe79ac38)

    Note:

    If the user is not part of the Administrators group, follow this procedure to explicitly allow a remote desktop connection for the user.

    1. From the Oracle Access Management Console, navigate to the Remote tab through Control Panel -> Remote Settings -> System Properties.

    2. Select the "allow connections from computers running any version of Remote Desktop" option.

    3. Click Select Users.

    4. Add the user.

    5. Click Apply.

  7. Copy the newly created keytab file to the proper location on the OAM Server and ensure permissions are correct so that the user who created Access Manager can access this file for running ktpass command.

  8. Create a simple OAM Server Kerberos krb5.conf or krb5.ini configuration. For example:

    [libdefaults]
    default_realm = lm.example.com
    ticket_lifetime = 600
    clock_skew = 600
    
    [realms]
    lm.example.com = { -- 
    kdc = kdc.lm.example.com
    admin_server = kdc.lm.example.com 
    default_domain = lm.example.com
    }
    [domain_realm] 
    lm.example.com =LM.EXAMPLE.COM
    .lm.example.com = LM.EXAMPLE.COM
    

    Note:

    The OAM account is created in one domain that is trusted by all, lm.example.com. This is not required for lmsib.sprite.com.

  9. Verify the klist and kinits work using the keytab file and SPN of the Active Directory and Access Manager user created, then record the results.

    1. kdestroy

    2. klist [-k] [-t <keytab_filename>]. For example:

      bash-3.2$ klist -k -t -K -e FILE:/refresh/home/oam.keytab
      Keytab name: FILE:/refresh/home/oam.keytab
      KVNO Timestamp Principal
      ---- ----------------- ---------------------------------------------------
      3 12/31/69 19:00:00 HTTP/oam11g.example.com@lm.example.com (ArcFour 
      with HMAC/md5)(0xa3a685f89364d4a5182b028fbe79ac38)
      bash-3.2$
      
    3. kdestroy

    4. kinit [-k] [-t <keytab_filename>] [<principal>]. For example:

      klist -k -t -K -e FILE:/refresh/home/oam.keytab
      
      bash-3.2$ kinit -V -k -t /refresh/home/oam.keytab 
      HTTP/oam11g.example.com@lm.example.com
      Authenticated to Kerberos v5
      
    5. klist -e

      bash-3.2$ klist -e
      Ticket cache: FILE:/tmp/krb5cc_8000
      Default principal: HTTP/oam11g.example.com@lm.example.com
      
      Valid starting Expires Service principal
      02/25/12 18:46:55 02/25/12 18:56:55 krbtgt/LM.EXAMPLE.COM@LM.EXAMPLE.COM
      Etype (skey, tkt): ArcFour with HMAC/md5, AES-256 CTS mode with 96-bit 
      SHA-1 HMAC
      
      Kerberos 4 ticket cache: /tmp/tkt8000
      klist: You have no tickets cached
      bash-3.2$
      
  10. Proceed as follows:

    Successful: Continue with "Confirming Access Manager Operations".

    Not Successful: Stop and resolve the issue which is not related to this integration. Any failure at this point indicates Access Manager WNA cannot work.

46.3 Confirming Access Manager Operations

You need a fully-functioning Access Manager deployment.

The tasks in this section are required regardless of the approach you choose. In this procedure you will install and register a WebGate, which configures an Application Domain to protect resources. Then you verify that the environment is working with an authentication scheme other than Kerberos.

See Also:

Creating a High Availability Environment in the High Availability Guide for details about high availability environments with two or more Managed Servers configured to operate as a cluster

  1. Log in to the Oracle Access Management Console using Administrator credentials.
  2. Verify the Default Identity Store connection.
  3. Register and install WebGate as an OAM Agent and accept automatic policy generation.
  4. Add resources to the Application Domain and customize the authentication policy protecting resources to use any Authentication Scheme other than Kerberos.
  5. Test the configuration to ensure that resource protection and access are working as expected.
  6. Proceed to Enabling the Browser to Return Kerberos Tokens

46.4 Enabling the Browser to Return Kerberos Tokens

You can configure the Internet Explorer or Mozilla Firefox browsers to return Kerberos tokens.

Perform the appropriate procedure on all Active Directory servers. Use either of the following procedures to configure the browsers.

Note:

With Internet Explorer browsers, Integrated Windows Authentication is enabled by default and you might not need any changes to the default configuration for WNA to work.

46.4.1 Enabling Kerberos Tokens in Internet Explorer

You can enable Kerberos token in Internet Explorer.

To enable Kerberos token:

  1. On a Windows host in the Active Directory domain, sign in as a domain user.
  2. Open the Internet Explorer browser.
  3. From the Tools menu, click Internet Options, click Security, click Local Intranet, click Advanced.
  4. On the Advanced tab, Security section, check the box beside Enable Integrated Windows Authentication, and click OK.
  5. Add Oracle Access Manager CC host or domain name to Local Intranet zone (use the format http://node.host:port (the port is not required)). For example:
    http://oam11g.example.com
  6. Restart the Internet Explorer browser to enable the change.

46.4.2 Enabling Kerberos Tokens in Mozilla Firefox

You can enable Kerberos tokens in Mozilla Firefox.

To enable Kerberos tokens:

  1. In the browser Address bar, enter about:config.
  2. Add Oracle Access Manager CC host or domain name under network.negotiate-auth.trusted-uris as: network.negotiate-auth.trusted-uris=http://oam11g.example.com

    Multiple URIs are separated with a comma.

46.5 Integrating KerberosPlugin with Oracle Virtual Directory

Oracle Virtual Directory provides the ability to integrate LDAP-aware applications into diverse directory environments while minimizing or eliminating the need to change either the infrastructure or the applications.

This section provides the tasks you must perform to configure Access Manager KerberosPlugin authentication for WNA with Oracle Virtual Directory.

  1. Perform tasks in this section:
  2. Configuring Access Manager for Windows Native Authentication
  3. Enabling the Browser to Return Kerberos Tokens
  4. Validating WNA with Access Manager Protected Resources

46.5.1 Preparing Oracle Virtual Directory for Integration

Oracle Virtual Directory communicates with other directories through adapters. Before you can start using Oracle Virtual Directory as an identity store, you must create adapters to each of the directories you want to use.

The procedure differs slightly, depending on the directory to which you are connecting. If you choose to use Oracle Internet Directory, Active Directory, Oracle Directory Server Enterprise Edition (ODSEE), or Oracle Unified Directory, the required adapters are created and configured while installing and configuring the Oracle Identity Management Server. For more information on managing the adapters, see "Managing Identity Virtualization Library (libOVD) Adapters" in the Integration Guide for Oracle Identity Management Suite.

In the following procedure you create an account for the OAM Server in the trusted domain. Additionally, you create two Active Directory Adapters (one for each forest) using the fully-qualified domain names as namespaces. By default Active Directory uses dc to construct the root context distinguished name. If this is different in your deployment, adjust your adapter namespaces accordingly.

  1. Perform tasks described in "Confirming Access Manager Operations".

  2. Install Oracle Virtual Directory, as described in Installing and Configuring Oracle Identity and Access Management.

  3. In Oracle Virtual Directory Console, create two Active Directory Adapters (one for each forest) using the fully-qualified domain names as namespaces as follows:

    1. Adapter 1, EXAMPLE Adapter namespace (domain DNS lm.example.com):

      dc=lm,dc=example,dc=com
      
    2. Adapter 2, SPRITE Adapter namespace (domain DNS lmsib.sprite.com):

      dc=lmsib,dc=sprite,dc=com
      
  4. Shut down the OAM Cluster.

  5. Restart the AdminServer and all OAM Servers.

  6. Proceed with "Registering Oracle Virtual Directory as the Default Store for WNA".

46.5.2 Registering Oracle Virtual Directory as the Default Store for WNA

Users with valid Oracle Access Management Administrator credentials can register Oracle Virtual Directory as the user store for Access Manager interoperating with Windows Native Authentication.

For Windows Native Authentication, the user credentials must reside in Microsoft Active Directory. Access Directory can be managed by Oracle Virtual Directory instance. For single sign-on with Access Manager, each User Identity Store must be registered to operate with Access Manager.

Typically, userprincipalname reflects the Windows login name. For WNA with Access Manager, either leave the User Search Base and Group Search Base blank or provide the distinguished name path that is common to both the adapters configured while performing prerequisite tasks. Before you begin, be sure to complete the sections About Preparing Your Active Directory and Kerberos Topology and Confirming Access Manager Operations.

  1. In the Oracle Access Management Console, click Configuration at the top of the window.
  2. Click User Identity Stores.
  3. In the OAM ID Stores section, click Create.
  4. Enter required values for your Oracle Virtual Directory instance. For example:
    • Name: OVD
    • LDAP Url: ldap://ovd_host.domain.com:389
    • Principal: cn=Administrator,cn=users,dc=lm,dc=example,dc=com
    • Credential: ********
    • User Search Base: dc=com
    • User Name Attribute: userprincipalname
    • Group Name: cn
    • Group Search Base: dc=com
    • LDAP Provider: Oracle Virtual Directory
  5. Default Store: Click the Default Store button to make this the user Identity Store for Access Manager.
  6. Click Apply to submit the registration, then dismiss the Confirmation window.
  7. Restart the AdminServer and OAM Servers.
  8. Proceed to "Setting Up Authentication with Access Manager KerberosPlugin and OVD".

46.5.3 Setting Up Authentication with Access Manager KerberosPlugin and OVD

When a native authentication module does not offer enough flexibility for your needs, you can create a custom authentication module using plug-ins designed to meet specific needs.

The KerberosPlugin is a credential mapping module that matches the credentials (encrypted username in the Kerberos ticket (SPNEGO token)) of the user who requests the resource. By default, KerberosPlugin maps the domain DNS name to the corresponding distinguished name using the dc component. However, if the mapping is different, you can specify the correct mapping as a semi-colon (;) separated list of name:value tokens. For example:

LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.SPRITE.COM:dc=lmsib,dc=sprite,dc=com

Users with valid Oracle Access Management Administrator credentials can perform the following task to replace default KerberosPlugin steps with steps that enable integration for Windows Native Authentication using the Oracle Access Management Console.

  1. In the Oracle Access Management Console, click Application Security at the top of the window.

  2. Click Authentication Modules in the Plug-ins section.

  3. Click Search, locate the KerberosPlugin plug-in and open it for editing.

  4. On the KerberosPlugin page, click the Steps tab.

    Steps Tab: Replace stepKTA, as described here, then click Save.

    1. Click stepKTA then click the Delete (x) button to remove this step.

    2. Click the Add (+) button and add the following step to the plug-in:

      Element Description

      Name

      stepKTA

      Class

      KerberosTokenAuthenticator

    Step Details:

    Edit this new stepKTA to change the Step Orchestration value from NULL (defined during the step deletion) to its default value of:

    On Success: StepUIF Failure Failure
    

    Also, confirm that this new stepKTA includes the parameter KEY_DOMAIN_DNS2DN_MAP (created earlier), enter the appropriate values for your deployment and click Save.

    Element Description

    KEY_DOMAIN_DNS2DN_MAP

    Active Directory Forests in your deployment. For example:

    LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.SPRITE.COM:dc=lmsib,dc=sprite,dc=com

    Note: By default, a DN domain name a.b.c is mapped into dc=a,dc=b,dc=c. Only if the mapping is different, one has to specify the parameter. Otherwise it is best not to use it and let the default behavior take its course.

    Service Principal

    HTTP/oam11g.example.com@LM.EXAMPLE.COM

    keytab.conf

    keytab.conf location for stepKTA

    krb5.conf

    krb5.conf location for stepKTA

  5. stepUIF Details: Configure as follows and click Save:

    Element Description

    KEY_LDAP_FILTER

    (samAccountName={KEY_USERNAME})

    KEY_IDENTITY_STORE_REF

    OVD

    KEY_SEARCHBASE_URL

    Leave this empty

  6. stepUI and stepUA: Configure as follows and Save:

    Element Description

    KEY_IDENTITY_STORE_REF

    OVD

  7. Save the changes.

  8. Restart the OAM Cluster.

  9. Proceed with "Configuring Access Manager for Windows Native Authentication".

46.6 Integrating the KerberosPlugin with Search Failover

In cases where an Oracle Virtual Directory deployment is not viable, and it is acceptable to perform search failover based on some order or hierarchy when finding the user, you can configure Access Manager.

  1. Complete tasks in the following earlier sections:
  2. Perform tasks in this section:
  3. "Configuring Access Manager for Windows Native Authentication"
  4. "Validating WNA with Access Manager Protected Resources"

46.6.1 Registering Microsoft Active Directory Instances with Access Manager

Users with valid Oracle Access Management Administrator credentials can register each Active Directory Global Catalog (ADGC), with relevant search bases and naming attributes, as an individual User Identity Store for Oracle Access Management.

A fully-configured Microsoft Active Directory authentication service should be set up with User accounts for mapping Kerberos services, Service Principal Names (SPNs) for those accounts, and Key tab files. For more information, see Oracle Fusion Middleware Securing Oracle WebLogic Server 11g Release 1 (10.3.3).

  1. In the Oracle Access Management Console, click Configuration at the top of the window.
  2. Click User Identity Stores.
  3. In the OAM ID Stores section, click Create.
  4. Enter required values for your first ADGC. For example:
    • Name: ADGC1-EXAMPLE
    • LDAP Url: ldap://ADGC1_host.domain.com:389
    • Principal: cn=Administrator,cn=users,dc=lm,dc=example,dc=com
    • Credential: ********
    • User Search Base: dc=lm,dc=example,dc=com
    • User Name Attribute: userprincipalname
    • Group Search Base: dc=lm,dc=example,dc=com
    • LDAP Provider: AD
  5. Default Store: Click the Default Store button.
  6. Click Apply to submit the changes and dismiss the confirmation window.
  7. Repeat these steps to add the second ADGC (ADGC2-SPRITE) with appropriate search bases and naming attributes.
    • Name: ADGC2-SPRITE
    • LDAP Url: ldap://ADGC2_host.domain.com:389
    • Principal: cn=Administrator,cn=users,dc=lm,dc=example,dc=com
    • Credential: ********
    • User Search Base: dc=lmsib,dc=example,dc=com
    • User Name Attribute: userprincipalname
    • Group Search Base: dc=lmsib,dc=example,dc=com
    • LDAP Provider: AD
  8. Restart the AdminServer and OAM Servers.
  9. Proceed to "Setting Up the KerberosPlugin for ADGCs".

46.6.2 Setting Up the KerberosPlugin for ADGCs

When a native authentication module does not offer enough flexibility for your needs, you can create a custom authentication module using plug-ins designed to meet specific needs. The KerberosPlugin is a credential mapping module that matches the credentials (username and password) of the user who requests a resource to the encrypted "Kerberos ticket". By default, KerberosPlugin maps the domain DNS name to the corresponding distinguished name using the dc component.

However, if the mapping is different, you can specify the correct mapping as a semi-colon (;) separated list of name:value tokens. For example:

LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.SPRITE.COM:dc=lmsib,dc=sprite,dc=com

Users with valid Oracle Access Management Administrator credentials can perform the following task to replace or update KerberosPlugin steps with steps that point to the ADGCs you have created. These will operate in tandem with their counterparts (if the initial step and ADGC fail, the secondary ADGC is used). Before you begin, be sure to complete the sections About Preparing Your Active Directory and Kerberos Topology and Confirming Access Manager Operations.

  1. In the Oracle Access Management Console, click Application Security at the top of the window.

  2. Click Authentication Modules in the Plug-ins section.

  3. Click Search, locate the KerberosPlugin plug-in and open it for editing.

  4. On the KerberosPlugin page, click the Steps tab.

    Steps Tab: Replace stepKTA, as described here, then click Save.

    1. Click stepKTA then click the Delete (x) button to remove this step.

    2. Click the Add (+) button and add the following step to the plug-in:

      Element Description

      Name

      stepKTA

      Class

      KerberosTokenAuthenticator

    New stepKTA Details:

    Confirm that this new stepKTA includes the parameter KEY_DOMAIN_DNS2DN_MAP (created earlier) and enter values for your deployment:

    Element Description

    KEY_DOMAIN_DNS2DN_MAP

    LM.EXAMPLE.COM:dc=lm,dc=example,dc=com;LMSIB.SPRITE.COM:dc=lmsib,dc=sprite,dc=com

    Service Principal

    HTTP/oam11g.example.com@LM.EXAMPLE.COM

    keytab.conf

    keytab.conf location for stepKTA. For example:

    /refresh/home/oam.keytab

    krb5.conf

    krb5.conf location for stepKTA.

    /etc/krb5.conf

  5. stepUIF: Step Details (configure as follows and save):

    Element Description

    KEY_IDENTITY_STORE_REF

    ADGC1-ORACLE

    KEY_SEARCHBASE_URL

    {KEY_USERDOMAIN}

    KEY_LDAP_FILTER

    (samAccountName={KEY_USERNAME}) NOTE: For untrusted, multi-domain Active Directory environments, use the userPrincipalName user attribute.

  6. stepUI and stepUA: Step Details (configure these steps and save):

    Element Description

    KEY_IDENTITY_STORE_REF

    ADGC1-ORACLE

  7. Save the changes.

  8. Add stepUIF2: This will operate in tandem and execute if stepUIF fails:

    Element Description

    KEY_IDENTITY_STORE_REF

    ADGC2-SPRITE

    KEY_SEARCHBASE_URL

    {KEY_USERDOMAIN}

    KEY_LDAP_FILTER

    (samAccountName= {KEY_USERNAME}) NOTE: For untrusted, multi-domain Active Directory environments, use the userPrincipalName user attribute.

  9. Add stepUI2: This will operate in tandem and execute if stepUI fails:

    Element Description

    KEY_IDENTITY_STORE_REF

    ADGC2-SPRITE

  10. Add stepUA2: This executes when stepUI2 succeeds:

    Element Description

    KEY_IDENTITY_STORE_REF

    ADGC1-EXAMPLE and ADGC2-SPRITE, respectively

  11. Add Step Details: Common Configuration, Plugins, KerberosTokenAutheticator.

    Enter values for your deployment:

    Element Description

    keytab.conf

    keytab.conf location for stepKTA. For example: /refresh/home/oam.keytab

    krb5.conf

    krb5.conf location for stepKTA. For example: /etc/krb5.conf

  12. Restart the OAM Cluster.

  13. Proceed with "Configuring Access Manager for Windows Native Authentication".

46.7 Configuring Access Manager for Windows Native Authentication

Whether you are using Oracle Virtual Directory or Active Directory with Global Catalogs, this section provides the following topics with steps you can follow:

46.7.1 Creating the Authentication Scheme for Windows Native Authentication

Users with valid Oracle Access Management Administrator credentials can define an authentication scheme to use in policies protecting applications for Windows Native authentication.

Before you begin, be sure to complete one of the following sections: Integrating KerberosPlugin with Oracle Virtual Directory or Integrating the KerberosPlugin with Search Failover.

  1. In the Oracle Access Management Console, click Application Security at the top of the window.
  2. Click Authentication Schemes in the Access Manager section.
  3. Under Search, type KerberosScheme in the Name box and click Search.
  4. Click KerberosScheme in the search results to open it.

    Set (or confirm) the following attributes:

    Challenge Method: WNA

    Authentication Module: KerberosPlugin

  5. Finish configuring KerberosScheme for your deployment.
  6. Click Apply and close the confirmation window.
  7. Proceed to "Configuring Policies for Windows Native Authentication".

46.7.2 Configuring Policies for Windows Native Authentication

You edit (or create) an Application Domain and policies to protect resources for Windows Native Authentication.

Before you begin, complete Creating the Authentication Scheme for Windows Native Authentication.

  1. In the Oracle Access Management Console, click Application Security at the top of the window.

  2. Click Application Domains in the Access Manager section.

  3. Open (or Create) the desired Application Domain, as described in "Managing Application Domains Using the Console".

  4. Resource Definitions: Add Resource Definitions to the domain as described in "Adding and Managing Policy Resource Definitions".

  5. Authentication Policies:

    1. Open the Authentication Policies node, and open (or Create) the desired Authentication Policy with the following attributes:

      Authentication Scheme: KerbScheme as the and ensure that it includes the updated KerberosPlugin.

      Choose KerbScheme as the Authentication Scheme and ensure that it includes the updated KerberosPlugin.

    2. Click Apply, close the Confirmation window.

    3. Resources for Authentication Policy: Add Resources to the Authentication Policy as described in the Administering Oracle Access Management.

    4. Complete the Authentication Policy with any desired Responses.

  6. Authorization Policies: Complete the Authentication Policy with any desired Responses or Conditions as described in "Defining Authorization Policies for Specific Resources".

  7. Proceed to "Verifying the Access Manager Configuration File".

46.7.3 Configuring WNA for NTLM Fallback

You can configure Access Manager to use WNA Fallback Authentication upon receiving an NTLM token.

For more information, see Understanding Access Manager WNA Login and Fall Back Authentication.

To configure:

  1. Stop the OAM managed server.

  2. Back up the following file to a safe location:

    <WLS domain>/config/fmwconfig/oam-config.xml

  3. Modify <WLS domain>/config/fmwconfig/oam-config.xml as follows:

    1. Find the following line:

      <Setting Name="CredentialCollector" Type="htf:map">
      
    2. After the line, add the following elements (if they are not already present):

      --------------------------------------------------------------------------
             <Setting Name="WNAOptions" Type="htf:map">
             <Setting Name="HandleNTLMResponse" Type="xsd:string">BASIC</Setting>
             </Setting>
       
      --------------------------------------------------------------------------
      

      If the following parameter already exists:

      <Setting Name="HandleNTLMResponse" Type="xsd:string">DEFAULT</Setting>
      

      change the HandleNTLMResponse value from DEFAULT to BASIC. For example:

      <Setting Name="HandleNTLMResponse" Type="xsd:string">BASIC</Setting> 
      
  4. Restart the OAM server processes.

    Note:

    See Two BASIC Authentication Prompts Are Displayed for troubleshooting information.

46.7.4 Configuring WNA Fallback to FORM-based Authentication Scheme

The OAM_WNA_OPT_OUT is a host-scoped persisting encrypted cookie set by the OAM Server. This cookie indicates the OAM server to challenge the user with FORM-based authentication when the browser presenting the cookie is not supporting WNA authentication. When set to TRUE, the OAM_WNA_OPT_OUT cookie makes the OAM server to change the authentication scheme from DEFAULT or BASIC to FORM-based before displaying the protected resource.
Upon receiving the NTLM tokens, OAM servers fall back to other authentication mechanisms. When HandleNTLMResponse is set to BASIC, the OAM server falls back to BASIC authentication scheme.

The WNA fallback to FORM-based authentication scheme relies on setting the pre-authentication rule. Create a pre-authentication rule that checks for OAM_WNA_OPT_OUT cookie which supports WNA FORM fallback mechanism. If the value of the OAM_WNA_OPT_OUT cookie is set TRUE, the authentication scheme is switched to FORM-based authentication.

  1. Stop the OAM managed server.

  2. Back up the <WLS domain>/config/fmwconfig/oam-config.xml file to a safe location.

  3. Edit <WLS domain>/config/fmwconfig/oam-config.xml as follows:

    <Setting Name="WNAOptions" Type="htf:map">
    <Setting Name="HandleNTLMResponse" Type="xsd:string">FORM</Setting>
    </Setting>
  4. When NTLM and Kerberos authentications do not work with a browser (such as a non-domain attached browser), the OAM Server responds with an authorization error (403) and HTML content in the body of the response. By default, OAM displays an authorization error page with a Login button. The user needs to click the Login button in the customized page to invoke WNA fallback to FORM-based authentication. You can optionally configure CustomOptOutPage or IsOptOutPersistent parameters in the oam-config.xml and customize the error page.

    1. Configure the Custom Opt Out Page as follows to emit all the HTML contents from the oam-config.xml file. The JavaScript function optOut() is invoked when a button in the customized page is clicked. Then OAM emits the JavaScript function optOut().

      <Setting Name="CustomOptOutPage" Type="xsd:string">/home/custom.html</Setting>
    2. The OAM_WNA_OPT_OUT cookie is set as persistent cookie, by default. Configure it as a session cookie as follows:
      <Setting Name="IsOptOutPersistent" Type="xsd:boolean">false</Setting>
  5. Verify if the value of the OAM_WNA_OPT_OUT cookie is set to TRUE and the pre-authentication condition is set as follows:
    str(request.requestMap['Cookie']).lower().find('oam_wna_opt_out=true') >= 0
  6. Restart the OAM server processes.

The OAM server falls back on FORM-based authentication scheme.

46.7.5 Verifying the Access Manager Configuration File

You can verify the Access Manager Configuration file, oam-config.xml.

Verify that the following are specified in the oam-config.xml file as in the following example:

  • path to the krb5.conf file

  • path to the keytab file

  • a principal to connect with KDC

oam-config.xml

<Setting Name="KerberosModules" Type="htf:map">
   <Setting Name="6DBSE52C" Type="htf:map">
      <Setting Name="principal"           Type="xsd:string">HTTP/oam11g.example.com@LM.EXAMPLE.COM
      </Setting>
      <Setting Name="name" Type="xsd:string">XYZKerberosModule</Setting>
      <Setting Name="keytabfile"           Type="xsd:string">/refresh/home/oam.keytab
      </Setting>
      <Setting Name="krbconfigfile" Type="xsd:string">/etc/krb5.conf</Setting>
   </Setting>
</Setting>

46.8 Validating WNA with Access Manager Protected Resources

Integrated Windows Authentication (IWA) is associated with Microsoft products that use SPNEGO, Kerberos, and NTLMSSP authentication protocols included with certain Windows operating systems.

The term Integrated Windows Authentication (IWA) is used for the automatic authentication process that happens between Microsoft Internet Information Services, Internet Explorer, and Microsoft's Active Directory.

Note:

IWA is also known by other names such as HTTP Negotiate authentication, NT Authentication, NTLM Authentication, Domain authentication, Windows Integrated Authentication, Windows NT Challenge/Response authentication and Windows Authentication.

WNA authentication occurs internally. When integrated with Access Manager:

  • The user is redirected to the Access Manager for authentication.

  • The OAM Server requests authentication with a www-negotiate header when the resource is protected by Access Manager with a challenge method of WNA.

  • The browser configured for Integrated Windows Authentication (IWA) sends the Kerberos SPNEGO token to the OAM Server for decryption.

  • The OAM Server decrypts the received user SPNEGO token (using keytab) and redirects the user back to the Agent with the cookie and gets access to the resource.

Use this procedure to validate WNA with Access Manager protected resources.

  1. Log in to a Windows system in the Active Directory domain as a domain user.
  2. Sign in to the Windows OS client using the Windows domain credentials stored in a hosted Active Directory that is registered with Access Manager.
  3. Open an Internet Explorer browser window, and enter the URL for the OAM-protected application in your environment.
  4. Confirm that you are logged in to the application with your Windows domain credentials with no additional login.

46.9 Configuring WNA For Use With DCC

The Kerberos authentication protocol provides a mechanism for mutual authentication between entities before a secure network connection is established.

This section provides information on how to configure Windows Native Authentication and Kerberos to use the DCC with Access Manager. It contains the following topics.

Note:

See Understanding Credential Collection and Login for details on DCC.

46.9.1 Initializing the Kerberos Protocol

You can initialize Access Manager for the Kerberos protocol.

To initialize:

  1. Run the ktpass command on the Windows data store, substituting the appropriate values for service, realm, user and user password.
    ktpass -princ <SPN>@<REALM> -pass <Password> -mapuser <UserName> 
     -out <Keytab file name>
    

    For example:

    ktpass -princ HTTP/adc.example1.com@EXAMPLE.COM -pass Welcome1 -mapuser anil@example.com -out foobar2.keytab
    

    This command creates an SPN and associates it with the local service account created in the previous step.

    Note:

    Only RC4-HMAC encryption is supported; do not use DES encryption.

  2. Copy the keytab output generated by the ktpass command and leave it at an appropriate location on the DCC host machine.
  3. Modify the /etc/krb5.conf file on the DCC host machine accordingly.

    For example:

    [loggings]
     default = FILE:/scratch/anikukum/krb/krb5libs.log
     kdc = FILE:/scratch/anikukum/krb/krb5kdc.log
     admin_server = FILE:/scratch/anikukum/krb/krbadmin.log
    
    [libdefaults]
     default_realm = EXAMPLE.COM
     ticket_lifetime = 24h
     forwardable = yes
     dns_lookup_realm = false
     dns_lookup_kdc = false
     default_tkt_enctypes = rc4-hmac
     default_tgs_enctypes = rc4-hmac
     permitted_enctypes = rc4-hmac
     clockskew = 3600
     
    [realms]
     EXAMPLE.COM = {
      kdc = adc.example1.com
      admin_server = adc.example1.com
      default_domain = EXAMPLE.COM
     }
     
    [domain_realm]
    example.com = EXAMPLE.COM.example.com = EXAMPLE.COM
    

    Note:

    For multiple domain Active Directory environments, add entries for each domain as documented below.

    [realms]
     EXAMPLE.COM = {
      kdc = adc.example1.com
      admin_server = adc.example1.com
      default_domain = EXAMPLE.COM
     }
     
     SPRITE.COM = {
      kdc = lmsib.sprite.com
      admin_server = lmsib.sprite.com
      default_domain = SPRITE.COM
     }
     
    [domain_realm]
    example.com = EXAMPLE.COM
    .example.com = EXAMPLE.COM
    sprite.com = SPRITE.COM
    .sprite.com = SPRITE.COM
    
  4. Run the kinit command on the DCC host machine to obtain a Kerberos ticket.
    kinit  -k -t <keytab file>  <SPN>@<Realm>
    

    For example:

    kinit -k -t foobar1.keytab HTTP/adc.example1.com@EXAMPLE.COM
    
  5. Validate the Kerberos ticket on the DCC host machine using the klist command.
    klist
    

46.9.2 Configuring Access Manager

You can configure Access Manager to use the Kerberos Authentication Module.

To configure:

  1. Modify the Challenge Method of the Kerberos authentication scheme to WNA, if applicable.

    1. In the Oracle Access Management Console, click Application Security at the top of the window.

    2. In the Launch Pad tab, click Authentication Schemes in the Access Manager section.

    3. Search for KerberosScheme and click Edit.

    4. Change the Challenge Redirect URL to DCC WebGate URL.

      For example, http://<DCC-WebGate-Hostname>:<Port>/

    5. Click Apply and close the page.

  2. Configure the User Identity Store for LDAP Authentication Module to the configured Windows data store.

    1. In the Oracle Access Management Console, click Application Security at the top of the window.

    2. In the Launch Pad tab, click Authentication Modules in the Access Manager section.

    3. Search for LDAP and click Edit.

    4. Change the User Identity Store to, for example, Active Directory.

    5. Click Apply and close the page.

  3. Configure the Application Domain protecting the resource to use the Kerberos authentication scheme.

    Before accessing the protected resource ensure that its URL is added to the local intranet Site of Security. Additionally, check the Enable Integrated Windows Authentication option under Security in the Advance tab.

46.10 Troubleshooting WNA Configuration

This section provides information about the following errors:

46.10.1 Kinit Fails

While retrieving initial credentials, the client may not be found in the Kerberos database.

This is the Kerberos version of "User not found" and might be related to one of the following:

  • Misspelling or typo of the principal name

  • The principal was not added to the Kerberos database, the principal doesn't exist.

  • The user name does not exist in Active Directory or has not been registered as a Kerberos user.

  • The SPN is not unique.

  • On the Active Directory side one or more duplicate entries were found.

The solution would be to have the Active Directory Administrator search the LDAP tree for duplicate entries of the SPN, and remove them.

46.10.2 "An Incorrect Username or Password was Specified" Is Displayed

If unable to access a resource protected by Access Manager using the WNA authentication scheme, the error message is displayed.

When the error message, "An incorrect Username or Password was specified" is displayed, check the following.

  • An incorrect username or password was specified.

  • There is a mismatch in the encryption types being used.

  • The key version number (kvno) of the SPN mentioned in the keytab does not match the kvno of the mapped user in the identity store.

46.10.3 User Identity Store is Not Registered Correctly

By default, the OAM identity store is Embedded LDAP. If you are using a different identity store (for example, Active Directory or Oracle Unified Directory) be sure to register the identity store.

Managing Data Sources has complete details on identity stores and how to register them.

46.10.4 Two BASIC Authentication Prompts Are Displayed

If OAM is configured for WNA and the client browser is not configured for IWA, two BASIC authentication prompts might be displayed when accessing a WNA protected resource.

One prompt comes from the Weblogic Server and the second from OAM. To avoid this, the WebLogic Server must be configured to ignore HTTP Basic authentication requests.

  1. Stop all WebLogic managed server and the admin server.
  2. Create a copy of the config.xml file.

    $WLS_DOMAIN/config/config.xml

  3. Add the following parameter at the end of the "<security-configuration>" section in the config.xml file.

    <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>

    Be sure to add this parameter BEFORE the <cross-domain-security-enabled>false</cross-domain-security-enabled> parameter.

  4. Restart the WebLogic environment.