22.8 Deploying and Managing Individual Plug-ins for Authentication

This section provides the following topics:

22.8.1 About Managing Your Own Authentication Plug-ins

You can create custom authentication plug-ins and use them to define customized multi-step authentication modules.

Using information in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management, the plug-ins can be created. After development, the plug-in must be deployed on the AdminServer, as a JAR file, which is validated automatically. After validation, an Administrator can configure and distribute the plug-in using the Oracle Access Management Console.

The server processes the XML configuration file within the plug-in JAR file to extract data about the plug-in. After the plug-in is imported, an Administrator can see and modify the various plug-in states based on information available from the AdminServer.

Figure 22-24 illustrates the Plug-ins Node under the Common Configuration section of the System Configuration tab, and the Plugins page. This Plugins page includes a tool bar with command buttons, most of which operate on the plug-in that is selected in the table. The table provides information about the existing custom plug-ins and their state. The Plugin Details section at the bottom of the page reflects configuration details for the selected plug-in the table.

Figure 22-24 Plug-ins Page

Description of Figure 22-24 follows
Description of "Figure 22-24 Plug-ins Page"

Administrators control plug-in states using the command buttons across the table at the top of the Plug-ins page, as described in Table 22-17.

Table 22-17 Managing Custom Plug-ins Actions

Action Button Description

Import Plugin...

Adds the plug-in JAR file to the AdminServer $DOMAIN_HOME/oam/plugins and begins plug-in validation.

  • Same JAR Name: If the new plug-in JAR name (in $DOMAIN_HOME/oam/plugins) matches an existing plug-in JAR name (in $DOMAIN_HOME/config/fmwconfig/oam/plugins), Oracle Access Manager extracts new configuration metadata from the XML file in the JAR (in $DOMAIN_HOME/oam/plugins) and checks the version of the new plug-in.

  • XML Version: If the new plug-in XML version (in $DOMAIN_HOME/oam/plugins) is greater than the existing XML version (in $DOMAIN_HOME/config/fmwconfig/oam/plugins), validation is successful. Otherwise, "invalid plugin name with invalid version" is returned and the new plug-in JAR is removed (from $DOMAIN_HOME/oam/plugins).

  • Different JAR Name: If the new plug-in JAR name (in $DOMAIN_HOME/oam/plugins) is different then existing plug-in JAR names (in $DOMAIN_HOME/config/fmwconfig/oam/plugins), the new plug-in JAR is uploaded and validation is successful.

On Success: Status is reported as "Uploaded" (even if an OAM Server is down). If all registered OAM Servers report "Uploaded", then the status on AdminServer is also "Uploaded".

On Failure: Status is reported as "Upload Failed"

See Also: "About the Custom Plug-in Life Cycle" in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management

Distribute Selected

  • Propagates the plug-in to all registered OAM Servers.

  • Sets the plug-in flag in oam-config.xml to "Distribute=true".

  • Starts the distribution listener and notification mechanism between AdminServer and OAM Servers

  • Distributes the plug-in JAR from AdminServer node to each OAM Server node under $DOMAIN_HOME/config/fmwconfig/oam/plugins

On Success: Status is reported as "Distributed" (even if an OAM Server is down). If all registered OAM Servers report "Distributed", then the status on AdminServer is also "Distributed".

On Failure: Status is reported as "Distribution Failed"

Activate Selected

After successful distribution the plug-in can be activated on all registered OAM Servers.

Activation:

  • Updates the plug-in flag in oam-config.xml to "Activate=true"

  • Starts the Message listener and notification mechanism between AdminServer and OAM Servers

  • AdminServer sends message "Activate" to all registered OAM Servers

On Success: Status is reported as "Activated" (even if an OAM Server is down). If all registered OAM Servers report "Activated", then the status on AdminServer is also "Activated".

On Failure: Status is reported as "Activation Failed"

Following activation on all OAM Servers, the plug-in can be used and executed in any authentication module construction or orchestration.

Deactivate Selected

Following plug-in activation, an Administrator can choose to deactivate the plug-in: if the plug-in is not used in any authentication module or scheme, for example. The selected plug-in from all registered OAM Servers.

Deactivate:

  • Updates the plug-in flag in oam-config.xml to "De-activate=true"

  • Starts the Distribution listener and notification mechanism between AdminServer and OAM Servers

  • Removes the plug-in JAR from AdminServer and each registered OAM Server ($DOMAIN_HOME/config/fmwconfig/oam/plugins)

  • AdminServer sends message "De-activation" to all registered OAM Servers

  • OAM Servers send status message to AdminServer using the "Message" listeners on both AdminServer and OAM Server

On Success: Status is reported as "De-activation" (even if an OAM Server is down). If all registered OAM Servers report "De-activation", then the status on AdminServer is also "De-activation". Plug-in configuration is removed from oam-config.xml.

Note: After deactivation, the plug-in cannot be used or executed in any authentication module or orchestration.

On Failure: Status is reported as "De-activation Failed"

Remove Selected

Following plug-in deactivation, an Administrator can delete the selected plug-in. During this process, Access Manager:

Delete:

  • Updates the plug-in flag in oam-config.xml to "Remove=true"

  • Starts the Distribution listener and notification mechanism between AdminServer and OAM Servers

  • Removes the plug-in JAR from AdminServer and each registered OAM Server ($DOMAIN_HOME/config/fmwconfig/oam/plugins)

  • AdminServer sends message "Activate" to all registered OAM Servers

On Success: Status is reported as "Removed" (even if an OAM Server is down). If all registered OAM Servers report "Removed", then the status on AdminServer is also "Removed". Plug-in configuration is removed from oam-config.xml.

On Failure: Status is reported as "Removal Failed"

Table 22-18 describes elements in the Plugins status table.

Table 22-18 Plugins Status Table

Element Description

Plugin Name

Extracted from the Plugin name element of the XML metadata file.

Description

Extracted from the description element of the XML metadata file.

Activation Status

Reported activation status based on information from AdminServer.

Type

Extracted from the type element of the XML metadata file.

Last Updated on

Extracted from the creation date element of the XML metadata file.

Last Updated by

Extracted from the author element of the XML metadata file.

In the Plugin Details section of the page, the Activation Status is maintained by the AdminServer, as shown in Table 22-18.

Figure 22-25 Plugin Details: Activation Status of Selected Plug-in

Description of Figure 22-25 follows
Description of "Figure 22-25 Plugin Details: Activation Status of Selected Plug-in"

Depending on your plug-in, various configuration details are extracted from the configuration element of the XML metadata file to populate Configuration Parameters in the Plugin Details section. Examples are shown in Table 22-19; see also, Table 22-13.

Table 22-19 Example of Plugin Details Extracted from XML Metadata File

Configuration Element Description

DataSource

 
- <configuration>
  - <AttributeValuePair>
      <Attribute type="string" length="20">DataSource</Attribute>
      <mandatory>true</mandatory>
      <instanceOverride>false</instanceOverride>
      <globalUIOverride>true</globalUIOverride>
      <value>jdbc/CISCO</value>
     <AttributeValuePair>
  <configuration>

Kerberos Details

Defines the following Kerberos details:

KEY_KEYTAB_FILE, KEY_PRINCIPAL, KEY_KRB_CONFIG_FILE

User Identification Details

Defines the User Identity Store and LDAP filter parameters. for this plug-in to use:

KEY_IDENTITY_STORE_REF, KEY_LDAP_FILTER

User Authentication Details

Defines the User Identity Store for this plug-in to use:

KEY_IDENTITY_STORE_REF

X.509 Details

Defines the X.509 certificate details for this plug-in to use:

KEY_CERTIFICATE_ATTRIBUTE_TO_EXTRACT, KEY_IS_CERT_VALIDATION_ENABLED

22.8.2 Making Custom Authentication Plug-ins Available for Use

Users with valid Administrator credentials can add, validate, distribute, and activate a custom plug-in.

Prerequisites

Developing a custom plug-in as described in the Oracle Fusion Middleware Developer's Guide for Oracle Access Management

  1. Import the Plug-in:

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

    2. In the Application Security Console, click Authentication Plug-ins in the Plug-ins section.

    3. In the page that appears, click Import Plug-in.

    4. In the Import Plugin dialog box, click Browse and select the name of your plug-in JAR file.

    5. Review the message in the dialog box, then click Import.

      The JAR file is validated as described in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

  2. Configure Parameters: Expand the Plugin Details section, click Configuration Parameters, and enter appropriate information as needed.

  3. Distribute the Plug-in to OAM Servers:

    1. In the Plug-ins table, select the target plug-in.

    2. Click Distribute Selected, then check the plug-in's Activation Status tab.

  4. Activate the Plug-in (and the custom plugin implementation class) so it is ready to be used by OAM Server:

    1. In the Plug-ins table, select the target plug-in.

    2. Click Activate Selected, then check the plug-in's Activation Status.

  5. Perform the following tasks as needed:

22.8.3 Checking an Authentication Plug-in's Activation Status

Users with valid Administrator credentials can activate a custom plug-in and check the status of activation.

Prerequisites

Making Custom Authentication Plug-ins Available for Use

  1. In the Oracle Access Management Console, click Application Security at the top of the window
  2. In the Application Security console, click Authentication Plug-ins in the Plug-ins section.
  3. In the Plug-ins table, select the target plug-in.
  4. Server Instance Name: Expand the Plug-in Details section and click Activation Status to display the location and status of the plug-in.
  5. Perform the following tasks as needed:

22.8.4 Deleting Your Custom Authentication Plug-ins

Users with valid Administrator credentials can deactivate and then delete a custom plug-in.

When an Administrator deletes a custom authentication plug-in, its name is not removed from the list of plug-ins. To delete the plug-in (for the purpose of re-importing the same plug-in later), the Administration must stop the WebLogic Server and edit the oam-config.xml manually.

Prerequisites

The plug-in must have been added and available in the console

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

  2. In the Application Security console, click Authentication Plug-ins in the Plug-ins section.

  3. Deactivate the Plug-in: You must perform this before removing a plug-in.

    1. In the Plug-ins table, select the target plug-in.

    2. Click Deactivate Selected, then check the plug-in's Activation Status.

  4. Delete the Deactivated Plug-in:

    1. In the Plug-ins table, select the target plug-in.

    2. Click Delete Selected.

    3. Stop the WebLogic Administration Server, locate and edit oam-config.xml manually to remove the deactivated plug-in, and then restart the WebLogic Administration Server.

  5. Perform the following tasks as needed: