44 Configuring JASPIC Security

The Java Authentication Service Provider Interface for Containers (JASPIC) specification defines a service provider interface (SPI) by which authentication providers that implement message authentication mechanisms can be integrated in server Web application message processing containers or runtimes. Learn how to configure JASPIC security in Oracle WebLogic Server.

Read the JASPIC specification at http://www.jcp.org/en/jsr/detail?id=196.

This chapter includes the following sections:

This section assumes that you are familiar with a basic overview of JASPIC, as described in JASPIC Security in Understanding Security for Oracle WebLogic Server.

JASPIC Mechanisms Override WebLogic Server Defaults

If you configure an Authentication Configuration Provider for a Web application, it is used instead of the WebLogic Server authentication mechanism for that Web Application. The JASPIC authentication provider assumes responsibility for authenticating the user credentials and returning a Subject.

You should therefore exercise care when you specify an Authentication Configuration Provider to make sure that it satisfies your security authentication needs.

Prerequisites for Configuring JASPIC

There are certain prerequisites for configuring JASPIC in your environment including, how to make your own or third party server authentication module (SAM) or Authentication Configuration Providers available to WebLogic Server.

The JASPIC programming model is described in the Java Authentication Service Provider Interface for Containers (JASPIC) specification (http://www.jcp.org/en/jsr/detail?id=196).

A sample SAM implementation is described in Adding Authentication Mechanisms to the Servlet Container in the GlassFish Server Open Source Edition Application Development Guide. Although written from the GlassFish Server perspective, the tips for writing a SAM, and the sample SAM itself, are instructive.

This section includes the following topics:

Server Authentication Module Must Be in Classpath

If you plan to configure a WebLogic Server Authentication Configuration Provider, you must add the jar for your SAM to the system classpath via the startup scripts or the command line used to start the WebLogic Server instance. If you do not do this, WebLogic Server is not able to find the appropriate classes.

Custom Authentication Configuration Providers Must Be in Classpath

If you plan to configure a custom Authentication Configuration Provider, you must add the jar for your custom Authentication Configuration Provider to the system classpath via the startup scripts or the command line used to start the WebLogic Server instance. If you do not do this, WebLogic Server is not able to find the appropriate classes.

Location of Configuration Data

You can use either the WebLogic Server Administration Console or the WebLogic Scripting Tool (WLST) to configure JASPIC and the Authentication Configuration Providers. After you configure JASPIC and the Authentication Configuration Providers, the domain-wide Authentication Configuration Provider configuration data is kept in the domain config.xml file in the <jaspic> element.

For example:

<jaspic>
      <auth-config-provider xsi:type="wls-auth-config-providerType">
        <name>WLSAuthConfigProvider-0</name>
      </auth-config-provider>
    </jaspic>

When you configure an Authentication Configuration Provider for a deployed Web application, the WebLogic Server Administration Console (or WLST) updates the deployment plan (plan.xml) for the Web application with the application-specific Authentication Configuration Provider configuration. For example:

<variable>
      <name>JASPICProvider_AuthConfigProviderName_13210476440805</name>
      <value>WLSAuthConfigProvider-0</value>
</variable>
:
<variable-assignment>
   <name>JASPICProvider_AuthConfigProviderName_13210476440805</name>
   <xpath>/weblogic-web-app/jaspic-provider/auth-config-provider-name</xpath>
</variable-assignment>

If you do not use a deployment plan for your application, you can instead add the jaspic-provider deployment descriptor element to weblogic.xml.

jaspic-provider specifies the authConfigProvider to be registered for use during authentication. For example, <wls:jaspic-provider>my-acp</wls:jlaspic-provider>.

Configuring JASPIC for a Domain

You can configure JASPIC for a domain using the Oracle WebLogic Server Administration Console.

By default, JASPIC is enabled for a domain. This means that you can configure JASPIC properties for the domain, and JASPIC is available for any Web applications for which you have specified an Authentication Configuration Provider.

See Configure Web applications for JASPIC in Oracle WebLogic Server Administration Console Online Help for the specific steps to follow to configure JASPIC in the WebLogic Server Administration Console.

If you disable JASPIC for a domain, JASPIC is then disabled for all Web applications in that domain, regardless of their configuration.

To configure JASPIC for a domain:

  1. In the left pane, select the name of the domain for which you want to configure JASPIC.
  2. Select Security > JASPIC > General.

    The JASPIC general page appears.

  3. Ensure that the Enable JASPIC control is set for this domain.
  4. Click Save.
  5. Select Security > JASPIC > Authentication Configuration Providers.

    The Authentication Configuration Providers page for the domain appears.

  6. Click New.
  7. From the drop-down list, select Create a New WLS Authentication Configuration Provider or Create a Custom WLS Authentication Configuration Provider.
  8. On the Create a New WLS Authentication Configuration Provider page, set the desired values on the Name and Server Authentication Module Class Name fields.

    You can accept the suggested name of WLSAuthConfigProvider-0, or use another name of your choice. The Server Authentication Module (SAM) Class Name identifies the Java class name of the SAM this Authentication Configuration Provider uses.

  9. On the Create a New Custom Authentication Configuration Provider page, set the desired values on the Name and Class Name fields.

    You can accept the suggested name of CustomAuthConfigProvider-0, or use another name of your choice. The class name is dependent on the implementation of your custom Authentication Configuration Provider.

  10. Enter the configuration properties for the Authentication Configuration Provider in the Configuration Properties text box.

    Each property must be on a separate line. For example: property1=value1.

  11. Click Finish.
  12. Restart WebLogic Server.

Displaying Authentication Configuration Providers

You can view the Authentication Configuration Providers for a domain by using the Oracle WebLogic Server Administration Console.

To display the Authentication Configuration Providers for a domain:

  1. In the left pane, select the name of the domain for which you want to display the Authentication Configuration Providers.
  2. Select Security > JASPIC > Authentication Configuration Providers.

    The Authentication Configuration Providers page for the domain appears.

  3. Select an existing Authentication Configuration Provider for which you want to display the configuration properties.

    The Settings page for this Authentication Configuration Provider appears.

  4. Optionally, click the Notes page and enter any site-specific configuration information you want to capture.
  5. If you made changes, click Save.
  6. If you made changes, restart WebLogic Server.

Configuring JASPIC for a Web Application

You can specify which, if any, Authentication Configuration Provider is to apply to a specific Web application by using the WebLogic Server Administration Console.

Before you can do this, you must first perform the following steps, as described in Configuring JASPIC for a Domain.

  1. Enable JASPIC in the domain.

  2. Configure a WebLogic Server Authentication Configuration Provider. Or,

  3. Configure a Custom Authentication Configuration Provider.

To configure JASPIC properties for this Web application:

  1. In the left pane of the Console, select Deployments.

    A table that lists the deployments currently installed on WebLogic Server appears in the right pane. The Type column specifies whether a deployment is an Enterprise application, a Web application, or an EJB module.

  2. In the right pane, click the name of the Web application you want to configure.
  3. Select Security > JASPIC to view and change the JASPIC properties.

    By default, JASPIC is disabled for Web applications. To enable JASPIC for this Web application, select one of the existing Authentication Configuration Providers from the drop-down list.

  4. Click Save to save any changes.
  5. Save the changes to the deployment plan, as prompted.
  6. Redeploy the Web application.
  7. Restart WebLogic Server.

Configuring JASPIC Using WLST

You can use WLST to configure JASPIC for a domain, and perform tasks such as creating a WLS Authentication Configuration Provider or a custom Authentication Configuration Provider, listing all WLS and custom Authentication Configuration Providers, enabling and disabling JASPIC for a domain.

For information about using WLST, see Understanding the WebLogic Scripting Tool.

This section requires you to configure the following MBeans via WLST:

See MBean Reference for Oracle WebLogic Server for additional MBean information.

Creating a WLS Authentication Configuration Provider

Example 44-1 creates a WLS Authentication Configuration Provider, sets the class name of the SAM, and sets a configuration property.

After you run this example, restart WebLogic Server.

Example 44-1 Create a WLS Authentication Configuration Provider

connect('','','t3://host:port')
Please enter your username :
Please enter your password :
...
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')
jaspic = cmo.getJASPIC()
wacp = jaspic.createWLSAuthConfigProvider('wacp')
am = wacp.getAuthModule()
am.setClassName('com.my.auth.module.Classname')
props = Properties()
props.setProperty('property', 'value')
am.setProperties(props)
save()
activate()

Creating a Custom Authentication Configuration Provider

Example 44-2 creates a custom Authentication Configuration Provider, sets the class name of this Authentication Configuration Provider, and sets a configuration property.

After you run this example, restart WebLogic Server.

Example 44-2 Create a Custom Authentication Configuration Provider

connect('','','t3://host:port')
Please enter your username :
Please enter your password :
...
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')
jaspic = cmo.getJASPIC()
acp = jaspic.createCustomAuthConfigProvider('cacp')
acp.setClassName('com.my.acp.Classname')
props = Properties()
props.setProperty('property', 'value')
acp.setProperties(props)
save()
activate()

Listing All WLS and Custom Authentication Configuration Providers

Example 44-3 shows how to list all Authentication Configuration Providers for a domain.

Example 44-3 List All Authentication Configuration Providers

connect('','','t3://host:port')
Please enter your username :
Please enter your password :
...
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')
jaspic = cmo.getJASPIC()
jaspic.getAuthConfigProviders()

Enabling JASPIC for a Domain

Example 44-4 shows how to enable JASPIC for a domain.

After you run this example, restart WebLogic Server.

Example 44-4 Enable JASPIC for a Domain

connect('','','t3://host:port')
Please enter your username :
Please enter your password :
...
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')
jaspic = cmo.getJASPIC()
jaspic.setEnabled(false)
save()
activate()

Disabling JASPIC for a Domain

Example 44-5 shows how to disable JASPIC for a domain.

After you run this example, restart WebLogic Server.

Example 44-5 Disable JASPIC for a Domain

connect('','','t3://host:port')
Please enter your username :
Please enter your password :
...
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')
jaspic = cmo.getJASPIC()
jaspic.setEnabled(false)
save()
activate()