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.

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:

   oam14c.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/oam14c.example.com@lm.example.com -mapuser oam -pass 
   examplepw -out c:\temp\oam.keytab
   
   C:\Users\Administrator>ktpass -princ HTTP/oam14c.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/oam14c.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/oam14c.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/oam14c.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/oam14c.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/oam14c.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.

To enable Kerberos token:

To enable Kerberos tokens:

To enable Kerberos tokens:

The procedure differs slightly, depending on the directory to which you are connecting. If you choose to use Oracle Internet Directory, Active Directory, 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".

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.

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/oam12c.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".

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.

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/oam12c.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".

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.

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".

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

To configure:

1. Stop the OAM managed server.

2. Export the oam-config.xml file from the database. See Updating OAM Configuration for details.

3. Edit 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. Import the modified oam-config.xml file into the database. See Updating OAM Configuration for details.

5. Restart the OAM server processes.

   Note:

   See Two BASIC Authentication Prompts Are Displayed for troubleshooting information.

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/oam12c.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>

To initialize:

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.

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.

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.

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

• To set the identity store being used as the Default Store, see About using the System Store for User Identities.

• To register the User Identity Store being used, see Registering a New User Identity Store with details in User Identity Store Settings.

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.