Developing Security Providers
If the security providers that ship with the WebLogic Enterprise Security product do not meet your needs, you can develop custom security providers by following the steps outlined in Overview of the Development Process on page 1-3.
This section covers the following topics:
You can develop the following types of custom security providers:
An Authentication provider is used to prove the identity of users or system processes. Authentication providers also remember, transport, and make that identity information available to various components of a system through subjects when needed. During the authentication process, a Principal Validation provider provides additional security protections for the principals (users and groups) contained within the subject by signing and verifying the authenticity of those principals.
An Identity Assertion provider is a specific form of Authentication provider that allows users or system processes to assert their identity using tokens (in other words, perimeter authentication). You can use an Identity Assertion provider in place of an Authentication provider if you create a LoginModule for the Identity Assertion provider, or in addition to an Authentication provider if you want to use the Authentication provider LoginModule. Identity Assertion providers enable perimeter authentication and support single sign-on.
Authentication providers rely on Principal Validation providers to sign and verify the authenticity of principals (users and groups) contained within a subject. Such verification provides an additional level of trust and may reduce the likelihood of malicious principal tampering. The authenticity of the principal is verified when making authorization decisions.
Role mapping is the process whereby principals (users or groups) are dynamically mapped to security roles at runtime. A Role Mapping provider determines which security roles apply to the principals stored a subject when the subject is attempting to perform an operation on a resource. Because this operation usually involves gaining access to the resource, Role Mapping providers are typically used with Authorization providers.
Authorization is the process whereby the interactions between users and resources are controlled, based on user identity or other information. In other words, authorization answers the question, What can you access? An Authorization provider is used to limit the interactions between users and resources to ensure integrity, confidentiality, and availability.
Adjudication involves resolving any authorization conflicts that may occur when more than one Authorization provider is configured, by weighing the result of each Access Decision. An Adjudication provider tallies the results that multiple Access Decisions return, and determines the final PERMIT
or DENY
decision. An Adjudication provider may also specify what should be done when an answer of ABSTAIN
is returned from a single Authentication provider.
An Auditing Provider processes information about operating requests and the outcome of those requests are collected, stored, and distributed for the purposes of non-repudiation. An Auditing provider provides this electronic trail of computer activity.
The MDF for the sample Authentication provider is called SampleAuthenticator.xml
.
To create an MBean Definition File (MDF), follow these steps:
Listing 4-1 SampleAuthenticator.xml MDF File
<?xml version="1.0" ?>
<!DOCTYPE MBeanType SYSTEM "commo.dtd">
<!-- MBean Definition File (MDF) for the Sample Authenticator.
Copyright (c) 2003 by BEA Systems, Inc. All Rights Reserved.
-->
<!-- Declare your mbean.
Since it is for an authenticator, it must extend the
weblogic.management.security.authentication.Authenticator mbean.
The Name and DisplayName cannot be the same.
They specify the name to appear on the
console for this provider.
Because this is an xml document, you can't use double
quotes directly. Instead you need to use "
Note that setting "Writeable" to "false" on an attribute
makes the attribute read-only. The default is read-write.
-->
<MBeanType
Name = "SampleAuthenticator"
DisplayName = "SampleAuthenticator"
Package = "examples.security.providers.authentication"
Extends = "weblogic.management.security.authentication.Authenticator"
>
<!-- You must set the value of the ProviderClassName attribute
(inherited from the weblogic.management.security.Provider mbean)
to the name of the java class you wrote that implements the
weblogic.security.spi.AuthenticationProvider interface.
You can think of the provider's mbean as the factory
for your provider's runtime implementation.
-->
<MBeanAttribute
Name = "ProviderClassName"
Type = "java.lang.String"
Writeable = "false"
Default = ""examples.security.providers.authentication.SampleAuthenticationProviderImpl""
/>
<!-- You must set the value of the Description attribute
(inherited from the weblogic.management.security.Provider mbean)
to a brief description of your provider.
It is displayed in the console.
-->
<MBeanAttribute
Name = "Description"
Type = "java.lang.String"
Writeable = "false"
Default = ""WLES Sample Authentication Provider""
/>
<!-- You must set the value of the Version attribute
(inherited from the weblogic.management.security.Provider mbean)
to your version of the provider. There is no required format.
-->
<MBeanAttribute
Name = "Version"
Type = "java.lang.String"
Writeable = "false"
Default = ""1.0""
/>
<!-- Add any custom attributes for your provider here.
The sample authenticator does not have any custom attributes.
-->
</MBeanType>
Note: A complete reference of MDF element syntax is available in MBean Definition File Element Syntax on page A-1.
After you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is a command-line utility that takes an MDF and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.
To generate the MBean type, follow these steps:
java -DMDF=
xmlfile -DFiles=
filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
-DMDF
is a flag that instructs the WebLogic MBeanMaker to translate the MDF into code.
xmlFile is the MDF (the XML MBean Description File).
filesdir is the location where the WebLogic MBeanMaker places the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by filesdir, the existing files are overwritten.
Each time you use the -DcreateStubs=true
flag, the MBeanMaker overwrites any existing MBean implementation file.
Note: The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple providers).
The MBean interface file is the client-side API to the MBean that your runtime class uses to obtain configuration data. The initialize method uses the MBean interface file. Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file has the same name as the MDF, appended with MBean. For example, the result of running the SampleAuthenticator
MDF through the WebLogic MBeanMaker yields an MBean interface file called SampleAuthenticatorMBean.java
.
This section describes how to create runtime classes for each type of provider. For more information about the SSPI and the methods described, see the Javadocs for Security Service Provider Interfaces.
To create the runtime classes for your custom Authentication provider, perform the following tasks:
For an example of how to create a runtime class for a custom Authentication provider, see Example: Creating the Runtime Classes for the Sample Authentication Provider on page 6-1.
To implement the AuthenticationProvider SSPI, provide implementations for the methods described in Table 3-1 and the weblogic.security.spi.AuthenticationProvider
interface methods, described in Table 4-1.
The For more information about the |
|
The The implementation of the |
|
The |
|
The |
To implement the JAAS javax.security.auth.spi.LoginModule
interface, provide implementations for the method described in Table 4-2.
The A CallbackHandler is a highly-flexible JAAS standard that allows a variable number of arguments to be passed as complex objects to a method. For more information about CallbackHandlers, see the Java 2 Enterprise Edition, v1.4.2 API Specification Javadoc for the CallbackHandler interface. |
|
The |
|
The |
|
The |
|
The |
For more information about the JAAS LoginModule
interface and the methods described above, see the Java Authentication and Authorization Service (JAAS) 1.0 Developer's Guide, and the Java 2 Enterprise Edition, v1.4.2 API Specification Javadoc for the LoginModule interface.
Optionally, you may want LoginModule that you write to throw a custom exception. The custom exception can be caught by your application and the appropriate action taken. For example, if the LoginModule throws a PasswordChangeRequiredException
, you can catch that exception within your application, and use it to forward users to a page that allows them to change their password.
You must make your custom exception available to both the Authentication provider (at build, compile, and runtime) and to your application at compile time. You can do this using either of the following two methods.
After creating any custom exceptions, you must create the runtime classes for your custom Identity Assertion provider. If you want to create a separate LoginModule for your custom Identity Assertion provider (that is, not use the LoginModule from your Authentication provider), you need to implement the JAAS LoginModule interface, as described in Implementing the JAAS LoginModule Interface on page 4-9.
For an example of how to create a runtime classes for a custom Identity Assertion provider, see Example: Creating the Runtime Class for the Sample Identity Assertion Provider on page 6-9.
To implement the AuthenticationProvider SSPI, provide implementations for the Security Provider interface methods described in Table 3-1 and the weblogic.security.spi.AuthenticationProvider
interface methods described in Table 4-1.
Note: When the LoginModule used for the Identity Assertion provider is the same as that used for an existing Authentication provider, implementations for the methods in the Authentication Provider SSPI (excluding the getIdentityAsserter
method) for Identity Assertion providers can just return null
. An example of this is shown in Listing 6-3.
To implement the IdentityAsserter SSPI, provide an implementation of the weblogic.security.spi.IdentityAsserter.assertIdentity()
method, described in Table 4-3.
The A CallbackHandler is a highly-flexible JAAS standard that allows a variable number of arguments to be passed as complex objects to a method. For more information about CallbackHandlers, see the Java 2 Enterprise Edition, v1.4.2 API Specification Javadoc for the CallbackHandler interface. |
To develop a custom Principal Validation provider:
UserImpl
and GroupImpl
classes by:weblogic.security.spi.WLSUser
and weblogic.security.spi.WLSGroup
interfaces. java.io.Serializable
interfaces.PrincipalValidationImpl
class by implementing the weblogic.security.spi.PrincipalValidator
SSPI. For instructions, see Implementing the PrincipalValidator SSPI.To implement the PrincipalValidator SSPI, provide implementations of the Principal Validator methods described in Table 4-4.
To create the runtime classes for your custom Role Mapping provider, perform the following tasks:
For an example of how to create a runtime class for a custom Role Mapping provider, see Example: Creating the Runtime Class for the Sample Role Mapping Provider on page 6-15.
To implement the RoleProvider SSPI, provide implementations for the methods described in Table 3-1 and the weblogic.security.spi.RoleProvider.getRoleMapper
method described in Table 4-5.
To implement the RoleMapper SSPI, provide implementations for the weblogic.security.spi.RoleMapper.getRoles
method described in Table 4-6.
|
The methods on the SecurityRole interface allow you to obtain basic information about a security role or to compare it to another security role. These methods are designed for the convenience of security providers.
Note: Security Role implementations are returned as a Map
by the getRoles()
method, keyed by role name.
To implement the Security Role interface, provide implementations for the weblogic.security.service.SecurityRole
interface methods described in Table 4-7.
To create the runtime classes for your custom Authorization provider, perform the following tasks:
For an example of how to create a runtime class for a custom Authorization provider, see Example: Creating the Runtime Class for the Sample Authorization Provider on page 6-12.
To implement the AuthorizationProvider SSPI, provide implementations for the methods described in Table 3-1 and the method described in Table 4-8.
When you implement the AccessDecision SSPI, you must provide implementations for the methods described in Table 4-9.
The |
|
The |
To create the runtime classes for your custom Adjudication provider, perform the following tasks:
To implement the AdjudicationProvider SSPI, provide implementations for the methods described in Table 3-1 and the weblogic.security.spi.AdjudicationProvider.getAdjudicator
method described in Table 4-10.
To implement the Adjudicator SSPI, provide implementations for the methods described in Table 4-11.
To create the runtime classes for your custom Auditing provider, perform the following tasks:
For an example of how to create a runtime class for a custom Auditing provider, see Example: Creating the Runtime Class for the Sample Auditing Provider.
To implement the AuditProvider SSPI, provide implementations for the methods described in Table 3-1 and the weblogic.security.spi.AuditProvider.getAuditChannel
method described in Table 4-12.
To implement the AuditChannel SSPI, provide an implementation for the weblogic.security.spi.AuditChannel.writeEvent
method described in Table 4-13.
The |
To create the runtime classes for your custom Credential Mapping provider, perform the following tasks:
To implement the CredentialProvider SSPI, provide implementations for the methods described in Table 3-1 and the weblogic.security.spi.CredentialProvider.getCredentialProvider
method described in Table 4-14.
The If there are two runtime classes, then the implementation of the
This is because the runtime class that implements the Credential Provider SSPI is used as a factory to obtain classes that implement the Credential Mapper SSPI. |
To implement the Credential Mapper SSPI, you must provide implementations for the weblogic.security.spi
.CredentialMapper
methods described in Table 4-15.
After you run your MDF through the WebLogic MBeanMaker to generate your custom MBean files, you need to package the MBean files and the runtime classes for the custom security provider into an MBean JAR file. The WebLogic MBeanMaker automates this process.
To create an MJF for your custom security provider, follow these steps:
java -DMJF=
jarfile -DFiles=
filesdir weblogic.management.commo.WebLogicMBeanMaker
-DMJF
is a flag instructing the WebLogic MBeanMaker to build an MBean JAR file containing the new provider.
jarfile is the name for the MBean JAR file.
filesdir is the location where the WebLogic MBeanMaker looks for the files to JAR into the MBean JAR file.
Compilation occurs at this point, so errors are possible. If jarfile is provided and no errors occur, an MBean JAR file is created with the specified name.
Notes: If you want to update an existing MBean JAR file, simply delete the MBean JAR file and regenerate it. The WebLogic MBeanMaker also has a -DIncludeSource
option that controls whether to include source files in the resulting MBean JAR file. Source files include both the generated source and the MBean definition file itself. The default is false
. This option is ignored when -DMJF
is not used.
The resulting MBean JAR file can be deployed into your WebLogic Enterprise Security environment or distributed for installation into other WebLogic Enterprise Security environments.
To deploy a security provider, copy the MJF file into the following directory:
PRODUCT_HOME
\lib\providers
PRODUCT_HOME
is the top-level installation directory for BEA WebLogic Enterprise Security product.
Note: You must copy the file to both the machine on which the Security Service Module is installed and to the Administration Server. You must copy the file to any and all instances of Security Service Modules that use the new provider.
This deploys your custom security provider—that is, you can configure the custom security provider from the Administration Application and us it with your Security Service Module instance.