Skip navigation.
Downloads | Product Documentation | Support

Developing Security Providers for WebLogic Server

# Authorization Providers

Authorization is the process whereby the interactions between users and WebLogic resources are controlled, based on user identity or other information. In other words, authorization answers the question, "What can you access?" In WebLogic Server, an Authorization provider is used to limit the interactions between users and WebLogic resources to ensure integrity, confidentiality, and availability.

The following sections describe Authorization provider concepts and functionality, and provide step-by-step instructions for developing a custom Authorization provider:

- Authorization Concepts
- The Authorization Process
- Do You Need to Develop a Custom Authorization Provider?
- How to Develop a Custom Authorization Provider

# Authorization Concepts

Before you develop an Authorization provider, you need to understand the following concepts:

- Access Decisions
- Security Providers and WebLogic Resources

## Access Decisions

Like LoginModules for Authentication providers, an Access Decision is the component of an Authorization provider that actually answers the "is access allowed?" question. Specifically, an Access Decision is asked whether a subject has permission to perform a given operation on a WebLogic resource, with specific parameters in an application. Given this information, the Access Decision responds with a result of `PERMIT`, `DENY`, or `ABSTAIN`.

Note: For more information about Access Decisions, see Implement the AccessDecision SSPI.

# The Authorization Process

Figure 6-1 illustrates how Authorization providers (and the associated Adjudication and Role Mapping providers) interact with the WebLogic Security Framework during the authorization process, and an explanation follows.

Figure 6-1 Authorization Providers and the Authorization Process

Generally, authorization is performed in the following manner:

1. A user or system process requests a WebLogic resource on which it will attempt to perform a given operation.
2. The resource container that handles the type of WebLogic resource being requested receives the request (for example, the EJB container receives the request for an EJB resource).

Note: The resource container could be the container that handles any one of the WebLogic Resources described in Security Providers and WebLogic Resources.

3. The resource container constructs a `ContextHandler` object that may be used by the configured Role Mapping providers and the configured Authorization providers' Access Decisions to obtain information associated with the context of the request.

Note: For more information about ContextHandlers, see ContextHandlers and WebLogic Resources. For more information about Access Decisions, see Access Decisions. For more information about Role Mapping providers, see Role Mapping Providers.

The resource container calls the WebLogic Security Framework, passing in the subject, the WebLogic resource, and optionally, the `ContextHandler` object (to provide additional input for the decision).

4. The WebLogic Security Framework calls the configured Role Mapping providers.
5. The Role Mapping providers use the `ContextHandler` to request various pieces of information about the request. They construct a set of `Callback` objects that represent the type of information being requested. This set of `Callback` objects is then passed as an array to the `ContextHandler` using the `handle` method.

The Role Mapping providers use the values contained in the `Callback` objects, the subject, and the resource to compute a list of security roles to which the subject making the request is entitled, and pass the list of applicable security roles back to the WebLogic Security Framework.

6. The WebLogic Security Framework delegates the actual decision about whether the subject is entitled to perform the requested action on the WebLogic resource to the configured Authorization providers.

The Authorization providers' Access Decisions also use the `ContextHandler` to request various pieces of information about the request. They too construct a set of `Callback` objects that represent the type of information being requested. This set of `Callback` objects is then passed as an array to the `ContextHandler` using the `handle` method. (The process is the same as described for Role Mapping providers in Step 5.)

7. The `isAccessAllowed` method of each configured Authorization provider's Access Decision is called to determine if the subject is authorized to perform the requested access, based on the `ContextHandler`, subject, WebLogic resource, and security roles. Each `isAccessAllowed` method can return one of three values:

- `PERMIT`—Indicates that the requested access is permitted.
- `DENY`—Indicates that the requested access is explicitly denied.
- `ABSTAIN`—Indicates that the Access Decision was unable to render an explicit decision.

This process continues until all Access Decisions are used.

8. The WebLogic Security Framework delegates the job of reconciling any discrepancies among the results rendered by the configured Authorization providers' Access Decisions to the Adjudication provider. The Adjudication provider determines the ultimate outcome of the authorization decision.

Note: For more information about the Adjudication provider, see Adjudication Providers.

9. The Adjudication provider returns either a `TRUE` or `FALSE` verdict, which is forwarded to the resource container through the WebLogic Security Framework.

- If the decision is `TRUE`, the resource container dispatches the request to the protected WebLogic resource.
- If the decision is `FALSE`, the resource container throws a security exception that indicates that the requestor was not authorized to perform the requested access on the protected WebLogic resource.

# Do You Need to Develop a Custom Authorization Provider?

The default (that is, active) security realm for WebLogic Server includes a WebLogic Authorization provider. The WebLogic Authorization provider supplies the default enforcement of authorization for this version of WebLogic Server. The WebLogic Authorization provider returns an access decision using a policy-based authorization engine to determine if a particular user is allowed access to a protected WebLogic resource. The WebLogic Authorization provider also supports the deployment and undeployment of security policies within the system. If you want to use an authorization mechanism that already exists within your organization, you could create a custom Authorization provider to tie into that system.

# How to Develop a Custom Authorization Provider

If the WebLogic Authorization provider does not meet your needs, you can develop a custom Authorization provider by following these steps:

1. Create Runtime Classes Using the Appropriate SSPIs
2. Generate an MBean Type Using the WebLogic MBeanMaker
3. Configure the Custom Authorization Provider Using the Administration Console
4. Provide a Mechanism for Security Policy Management

## Create Runtime Classes Using the Appropriate SSPIs

Before you start creating runtime classes, you should first:

- Understand the Purpose of the Provider SSPIs
- Determine Which Provider Interface You Will Implement
- Understand the SSPI Hierarchy and Determine Whether You Will Create One or Two Runtime Classes

When you understand this information and have made your design decisions, create the runtime classes for your custom Authorization provider by following these steps:

- Implement the AuthorizationProvider SSPI or Implement the DeployableAuthorizationProvider SSPI
- Implement the AccessDecision SSPI

Note: At least one Authorization provider in a security realm must implement the `DeployableAuthorizationProvider` SSPI, or else it will be impossible to deploy Web applications and EJBs.

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.

### Implement the AuthorizationProvider SSPI

To implement the `AuthorizationProvider` SSPI, provide implementations for the methods described in Understand the Purpose of the Provider SSPIs and the following method:

  getAccessDecision

  `public AccessDecision getAccessDecision();`

  The `getAccessDecision` method obtains the implementation of the `AccessDecision` SSPI. For a single runtime class called `MyAuthorizationProviderImpl`.`java`, the implementation of the `getAccessDecision` method would be:

  `return this;`

  If there are two runtime classes, then the implementation of the `getAccessDecision` method could be:

  `return new MyAccessDecisionImpl;`

  This is because the runtime class that implements the `AuthorizationProvider` SSPI is used as a factory to obtain classes that implement the `AccessDecision` SSPI.

For more information about the `AuthorizationProvider` SSPI and the `getAccessDecision` method, see the WebLogic Server 8.1 API Reference Javadoc.

### Implement the DeployableAuthorizationProvider SSPI

To implement the `DeployableAuthorizationProvider` SSPI, provide implementations for the methods described in Understand the Purpose of the Provider SSPIs, Implement the AuthorizationProvider SSPI, and the following methods:

  deployPolicy

  `public void deployPolicy(Resource resource, java.lang.String[] roleNames) throws ResourceCreationException`

  The `deployPolicy` method creates a security policy on behalf of a deployed Web application or EJB, based on the WebLogic resource to which the security policy should apply and the security role names that are in the security policy.

  undeployPolicy

  `public void undeployPolicy(Resource resource) throws ResourceRemovalException`

  The `undeployPolicy` method deletes a security policy on behalf of an undeployed Web application or EJB, based on the WebLogic resource to which the security policy applied.

For more information about the `DeployableAuthorizationProvider` SSPI and the `deployPolicy` and `undeployPolicy` methods, see the WebLogic Server 8.1 API Reference Javadoc.

### Implement the AccessDecision SSPI

When you implement the `AccessDecision` SSPI, you must provide implementations for the following methods:

  isAccessAllowed

  `public Result isAccessAllowed(Subject subject, Map roles,`

  `Resource resource, ContextHandler handler, Direction direction) throws InvalidPrincipalException`

  The `isAccessAllowed` method utilizes information contained within the subject to determine if the requestor should be allowed to access a protected method. The `isAccessAllowed` method may be called prior to or after a request, and returns values of `PERMIT`, `DENY`, or `ABSTAIN`. If multiple Access Decisions are configured and return conflicting values, an Adjudication provider will be needed to determine a final result. For more information, see Adjudication Providers.

  isProtectedResource

  `public boolean isProtectedResource(Subject subject, Resource resource) throws InvalidPrincipalException`

  The `isProtectedResource` method is used to determine whether the specified WebLogic resource is protected, without incurring the cost of an actual access check. It is only a lightweight mechanism because it does not compute a set of security roles that may be granted to the caller's subject.

For more information about the `AccessDecision` SSPI and the `isAccessAllowed` and `isProtectedResource` methods, see the WebLogic Server 8.1 API Reference Javadoc.

#### Developing Custom Authorization Providers That Are Compatible With the Realm Adapter Authentication Provider

An Authentication provider is the security provider responsible for populating a subject with users and groups, which are then extracted from the subject by other types of security providers, including Authorization providers. If the Authentication provider configured in your security realm is a Realm Adapter Authentication provider, the user and group information will be stored in the subject in a way that is slightly different from other Authentication providers. Therefore, this user and group information must also be extracted in a slightly different way.

Listing 6-1 provides code that can be used by custom Authorization providers to check whether a subject matches a user or group name when a Realm Adapter Authentication provider was used to populate the subject. This code belongs in both the `isAccessAllowed` and `isProtectedResource` methods.

Listing 6-1 Sample Code to Check if a Subject Matches a User or Group Name

>     /**
>      * Determines if the Subject matches a user/group name.
>      *
>      * @param principalWant A String containing the name of a principal in this role
>      * (that is, the role definition).
>      *
>      * @param subject A Subject that contains the Principals that identify the user
>      * who is trying to access the resource as well as the user's groups.
>      *
>      * @return A boolean. true if the current subject matches the name of the
>      * principal in the role, false otherwise.
>      */
>     private boolean subjectMatches(String principalWant, Subject subject)
>     {
>        // first, see if it's a group name match
>        if (SubjectUtils.isUserInGroup(subject, principalWant)) {
>           return true;
>        }
>        // second, see if it's a user name match
>        if (principalWant.equals(SubjectUtils.getUsername(subject))) {
>           return true;
>        }
>        // didn't match
>        return false;
>     }

### Example: Creating the Runtime Class for the Sample Authorization Provider

Listing 6-2 shows the `SampleAuthorizationProviderImpl.java` class, which is the runtime class for the sample Authorization provider. This runtime class includes implementations for:

- The three methods inherited from the `SecurityProvider` interface: `initialize`, `getDescription` and `shutdown` (as described in Understand the Purpose of the Provider SSPIs).
- The method inherited from the `AuthorizationProvider` SSPI: the `getAccessDecision` method (as described in Implement the AuthorizationProvider SSPI).
- The two methods in the `DeployableAuthorizationProvider` SSPI: the `deployPolicy` and `undeployPolicy` methods (as described in Implement the DeployableAuthorizationProvider SSPI).
- The two methods in the `AccessDecision` SSPI: the `isAccessAllowed` and `isProtectedResource` methods (as described in Implement the AccessDecision SSPI).

Note: The bold face code in Listing 6-2 highlights the class declaration and the method signatures.

Listing 6-2 SampleAuthorizationProviderImpl.java

>     package examples.security.providers.authorization;

>     import java.security.Principal;
>     import java.util.Enumeration;
>     import java.util.Iterator;
>     import java.util.Map;
>     import java.util.Set;
>     import javax.security.auth.Subject;
>     import weblogic.management.security.ProviderMBean;
>     import weblogic.security.WLSPrincipals;
>     import weblogic.security.service.ContextHandler;
>     import weblogic.security.spi.AccessDecision;
>     import weblogic.security.spi.DeployableAuthorizationProvider;
>     import weblogic.security.spi.Direction;
>     import weblogic.security.spi.InvalidPrincipalException;
>     import weblogic.security.spi.Resource;
>     import weblogic.security.spi.ResourceCreationException;
>     import weblogic.security.spi.ResourceRemovalException;
>     import weblogic.security.spi.Result;
>     import weblogic.security.spi.SecurityServices;

>     public final class SampleAuthorizationProviderImpl implements DeployableAuthorizationProvider, AccessDecision
>     {
>        private String description;
>        private SampleAuthorizerDatabase database;

>        public void initialize(ProviderMBean mbean, SecurityServices services)
>        {
>           System.out.println("SampleAuthorizationProviderImpl.initialize");
>           SampleAuthorizerMBean myMBean = (SampleAuthorizerMBean)mbean;
>           description = myMBean.getDescription() + "\n" + myMBean.getVersion();
>           database = new SampleAuthorizerDatabase(myMBean);
>        }

>        public String getDescription()
>        {
>           return description;
>        }

>        public void shutdown()
>        {
>           System.out.println("SampleAuthorizationProviderImpl.shutdown");
>        }

>        public AccessDecision getAccessDecision()
>        {
>           return this;
>        }

>        public Result isAccessAllowed(Subject subject, Map roles, Resource resource,
>        ContextHandler handler, Direction direction) throws InvalidPrincipalException
>        {
>           System.out.println("SampleAuthorizationProviderImpl.isAccessAllowed");
>           System.out.println("\tsubject\t= " + subject);
>           System.out.println("\troles\t= " + roles);
>           System.out.println("\tresource\t= " + resource);
>           System.out.println("\tdirection\t= " + direction);

>           Set principals = subject.getPrincipals();

>           for (Resource res = resource; res != null; res = res.getParentResource()) {
>              if (database.policyExists(res)) {
>                 return isAccessAllowed(res, principals, roles);
>              }
>           }
>           return Result.ABSTAIN;
>        }

>        public boolean isProtectedResource(Subject subject, Resource resource) throws
>        InvalidPrincipalException
>        {
>           System.out.println("SampleAuthorizationProviderImpl.
>             isProtectedResource");
>           System.out.println("\tsubject\t= " + subject);
>           System.out.println("\tresource\t= " + resource);

>           for (Resource res = resource; res != null; res = res.getParentResource()) {
>              if (database.policyExists(res)) {
>                 return true;
>              }
>           }
>           return false;
>        }

>        public void deployPolicy(Resource resource, String[] roleNamesAllowed)
>        throws ResourceCreationException
>        {
>           System.out.println("SampleAuthorizationProviderImpl.deployPolicy");
>           System.out.println("\tresource\t= " + resource);

>           for (int i = 0; roleNamesAllowed != null && i < roleNamesAllowed.length;
>            i++) {
>              System.out.println("\troleNamesAllowed[" + i + "]\t= " +
>              roleNamesAllowed[i]);
>           }
>           database.setPolicy(resource, roleNamesAllowed);
>        }

>        public void undeployPolicy(Resource resource) throws ResourceRemovalException
>        {
>           System.out.println("SampleAuthorizationProviderImpl.undeployPolicy");
>           System.out.println("\tresource\t= " + resource);

>           database.removePolicy(resource);
>        }

>        private boolean principalsOrRolesContain(Set principals, Map roles, String
>        principalOrRoleNameWant)
>        {
>           if (roles.containsKey(principalOrRoleNameWant)) {
>              return true;
>           }
>           {
>              for (Iterator i = principals.iterator(); i.hasNext();) {
>                 Principal principal = (Principal)i.next();
>                 String principalNameHave = principal.getName();
>                 if (principalOrRoleNameWant.equals(principalNameHave)) {
>                    return true;
>                 }
>              }
>           }
>           return false;
>        }

>        private Result isAccessAllowed(Resource resource, Set principals, Map roles)
>        {
>           for (Enumeration e = database.getPolicy(resource); e.hasMoreElements();)
>           {
>            String principalOrRoleNameAllowed = (String)e.nextElement();
>            if (WLSPrincipals.getEveryoneGroupname().
>              equals(principalOrRoleNameAllowed) ||
>              (WLSPrincipals.getUsersGroupname().equals(principalOrRoleNameAllowed)
>              && !principals.isEmpty()) || principalsOrRolesContain(principals,
>              roles, principalOrRoleNameAllowed))
>              {
>                 return Result.PERMIT;
>              }
>           }
>           return Result.DENY;
>        }
>     }

## Generate an MBean Type Using the WebLogic MBeanMaker

Before you start generating an MBean type for your custom security provider, you should first:

- Understand Why You Need an MBean Type
- Determine Which SSPI MBeans to Extend and Implement
- Understand the Basic Elements of an MBean Definition File (MDF)
- Understand the SSPI MBean Hierarchy and How It Affects the Administration Console
- Understand What the WebLogic MBeanMaker Provides

When you understand this information and have made your design decisions, create the MBean type for your custom Authorization provider by following these steps:

1. Create an MBean Definition File (MDF)
2. Use the WebLogic MBeanMaker to Generate the MBean Type
3. Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)
4. Install the MBean Type Into the WebLogic Server Environment

Notes: Several sample security providers (available under Code Samples: WebLogic Server on the dev2dev Web site) illustrate how to perform these steps.

All instructions provided in this section assume that you are working in a Windows environment.

### Create an MBean Definition File (MDF)

To create an MBean Definition File (MDF), follow these steps:

1. Copy the MDF for the sample Authorization provider to a text file.

Note: The MDF for the sample Authorization provider is called `SampleAuthorizer.xml`.

2. Modify the content of the `<MBeanType>` and `<MBeanAttribute>` elements in your MDF so that they are appropriate for your custom Authorization provider.
3. Add any custom attributes and operations (that is, additional `<MBeanAttribute>` and `<MBeanOperation>` elements) to your MDF.
4. Save the file.

Note: A complete reference of MDF element syntax is available in MBean Definition File (MDF) Element Syntax.

### Use the WebLogic MBeanMaker to Generate the MBean Type

Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input 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.

The instructions for generating an MBean type differ based on the design of your custom Authorization provider. Follow the instructions that are appropriate to your situation:

- No Optional SSPI MBeans and No Custom Operations
- Optional SSPI MBeans or Custom Operations

#### No Optional SSPI MBeans and No Custom Operations

If the MDF for your custom Authorization provider does not implement any optional SSPI MBeans and does not include any custom operations, follow these steps:

1. Create a new DOS shell.
2. Type the following command:

`java -DMDF=`xmlfile`-Dfiles=`filesdir`-DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMDF` flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place 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, you are informed that the existing files will be overwritten and are asked to confirm.

Each time you use the `-DcreateStubs=true` flag, it 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 Authorization providers).

3. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

#### Optional SSPI MBeans or Custom Operations

If the MDF for your custom Authorization provider does implement some optional SSPI MBeans or does include custom operations, consider the following:

- Are you creating an MBean type for the first time? If so, follow these steps:

1. Create a new DOS shell.
2. Type the following command:

`java -DMDF=`xmlfile`-Dfiles=`filesdir`-DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMDF` flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place 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, you are informed that the existing files will be overwritten and are asked to confirm.

Each time you use the `-DcreateStubs=true` flag, it 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 Authorization providers).

3. If you implemented optional SSPI MBeans in your MDF, follow these steps:

1. Locate the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanName `Impl.java`. For example, for the MDF named `SampleAuthorizer`, the MBean implementation file to be edited is named `SampleAuthorizerImpl.java`.

2. For each optional SSPI MBean that you implemented in your MDF, copy the method stubs from the Mapping MDF Operation Declarations to Java Method Signatures Document (available on the dev2dev Web site) into the MBean implementation file, and implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

4. If you included any custom operations in your MDF, implement the methods using the method stubs.
5. Save the file.
6. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

- Are you updating an existing MBean type? If so, follow these steps:

1. Copy your existing MBean implementation file to a temporary directory so that your current method implementations are not overwritten by the WebLogic MBeanMaker.
2. Create a new DOS shell.
3. Type the following command:

`java -DMDF=`xmlfile`-Dfiles=`filesdir`-DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMDF` flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place 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, you are informed that the existing files will be overwritten and are asked to confirm.

Each time you use the `-DcreateStubs=true` flag, it 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 Authorization providers).

4. If you implemented optional SSPI MBeans in your MDF, follow these steps:

1. Locate the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanName `Impl.java`. For example, for the MDF named `SampleAuthorizer`, the MBean implementation file to be edited is named `SampleAuthorizerImpl.java`.

2. Open your existing MBean implementation file (which you saved to a temporary directory in step 1).
3. Synchronize the existing MBean implementation file with the MBean implementation file generated by the WebLogic MBeanMaker.

Accomplishing this task may include, but is not limited to: copying the method implementations from your existing MBean implementation file into the newly-generated MBean implementation file (or, alternatively, adding the new methods from the newly-generated MBean implementation file to your existing MBean implementation file), and verifying that any changes to method signatures are reflected in the version of the MBean implementation file that you are going to use (for methods that exist in both MBean implementation files).

4. If you modified the MDF to implement optional SSPI MBeans that were not in the original MDF, copy the method stubs from the Mapping MDF Operation Declarations to Java Method Signatures Document (available on the dev2dev Web site) into the MBean implementation file, and implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

5. If you modified the MDF to include any custom operations that were not in the original MDF, implement the methods using the method stubs.
6. Save the version of the MBean implementation file that is complete (that is, has all methods implemented).
7. Copy this MBean implementation file into the directory where the WebLogic MBeanMaker placed the intermediate files for the MBean type. You specified this as filesdir in step 3. (You will be overriding the MBean implementation file generated by the WebLogic MBeanMaker as a result of step 3.)
8. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

#### About the Generated MBean Interface File

The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the Provider SSPIs.

Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the `SampleAuthorizer` MDF through the WebLogic MBeanMaker will yield an MBean interface file called `SampleAuthorizerMBean.java`.

### Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Authorization provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.

To create an MJF for your custom Authorization provider, follow these steps:

1. Create a new DOS shell.
2. Type the following command:

`java -DMJF=`jarfile`-Dfiles=`filesdir `weblogic.management.commo.WebLogicMBeanMaker`

where the `-DMJF` flag indicates that the WebLogic MBeanMaker should build a JAR file containing the new MBean types, jarfile is the name for the MJF and filesdir is the location where the WebLogic MBeanMaker looks for the files to JAR into the MJF.

Compilation occurs at this point, so errors are possible. If jarfile is provided, and no errors occur, an MJF is created with the specified name.

Notes: If you want to update an existing MJF, simply delete the MJF and regenerate it. The WebLogic MBeanMaker also has a `-DIncludeSource` option, which controls whether source files are included into the resulting MJF. Source files include both the generated source and the MDF itself. The default is `false`. This option is ignored when `-DMJF` is not used.

The resulting MJF can be installed into your WebLogic Server environment, or distributed to your customers for installation into their WebLogic Server environments.

### Install the MBean Type Into the WebLogic Server Environment

To install an MBean type into the WebLogic Server environment, copy the MJF into the WL_HOME`\server\lib\mbeantypes` directory, where WL_HOME is the top-level installation directory for WebLogic Server. This "deploys" your custom Authorization provider—that is, it makes the custom Authorization provider manageable from the WebLogic Server Administration Console.

Note: WL_HOME`\server\lib\mbeantypes` is the default directory for installing MBean types. However, if you want WebLogic Server to look for MBean types in additional directories, use the `-Dweblogic.alternateTypesDirectory=`<dir> command-line flag when starting your server, where <dir> is a comma-separated list of directory names. When you use this flag, WebLogic Server will always load MBean types from WL_HOME`\server\lib\mbeantypes` first, then will look in the additional directories and load all valid archives present in those directories (regardless of their extension). For example, if `-Dweblogic.alternateTypesDirectory = dirX,dirY`, WebLogic Server will first load MBean types from WL_HOME`\server\lib\mbeantypes`, then any valid archives present in `dirX` and `dirY`. If you instruct WebLogic Server to look in additional directories for MBean types and are using the Java Security Manager, you must also update the `weblogic.policy` file to grant appropriate permissions for the MBean type (and thus, the custom security provider). For more information, see Using the Java Security Manager to Protect WebLogic Resources in Programming WebLogic Security.

You can create instances of the MBean type by configuring your custom Authorization provider (see Configure the Custom Authorization Provider Using the Administration Console), and then use those MBean instances from a GUI, from other Java code, or from APIs. For example, you can use the WebLogic Server Administration Console to get and set attributes and invoke operations, or you can develop other Java objects that instantiate MBeans and automatically respond to information that the MBeans supply. We recommend that you back up these MBean instances. For more information, see Backing Up Configuration and Security Data under "Recovering Failed Servers" in Configuring and Managing WebLogic Server.

## Configure the Custom Authorization Provider Using the Administration Console

Configuring a custom Authorization provider means that you are adding the custom Authorization provider to your security realm, where it can be accessed by applications requiring authorization services.

Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers. This section contains information that is important for the person configuring your custom Authorization providers:

- Managing Authorization Providers and Deployment Descriptors
- Enabling Security Policy Deployment

Note: The steps for configuring a custom Authorization provider using the WebLogic Server Administration Console are described under Configuring a Custom Security Provider in Managing WebLogic Security.

### Managing Authorization Providers and Deployment Descriptors

Some application components, such as Enterprise JavaBeans (EJBs) and Web applications, store relevant deployment information in Java 2 Enterprise Edition (J2EE) and WebLogic Server deployment descriptors. For Web applications, the deployment descriptor files (called `web.xml` and `weblogic.xml`) contain information for implementing the J2EE security model, including declarations of security policies. Typically, you will want to include this information when first configuring your Authorization providers in the WebLogic Server Administration Console.

The Administration Console provides an On Future Redeploys drop-down menu for this purpose, which you or an administrator should be sure is set to Initialize Roles and Policies From DD the first time a custom Authorization provider is configured.

Notes: The On Future Redeploys drop-down menu is set to Initialize Roles and Policies from DD by default. To locate the On Future Redeploys drop-down menu, click Security —> Realms —> realm in the left pane of the Administration Console, where realm is the name of your security realm. Then select the General tab.

When the value of this drop-down menu is Initialize Roles and Policies From DD and a Web application is deployed, WebLogic Server reads security policy information from the `web.xml` and `weblogic.xml` deployment descriptor files (examples of `web.xml` and `weblogic.xml` files are shown in Listing 6-3 and Listing 6-4). This information is then copied into the security provider database for the Authorization provider.

Note: You can only change the value of the On Future Redeploys drop-down menu if the value of the Check Roles and Policies drop-down menu is All Web Applications and EJBs. For more information, see Techniques for Securing URL (Web) and EJB Resources and Prerequisites for Securing URL (Web) and EJB Resources in Securing WebLogic Resources.

Listing 6-3 Sample web.xml File

>     <web-app>

>        <welcome-file-list>
>           <welcome-file>welcome.jsp</welcome-file>
>        </welcome-file-list>

>        <security-constraint>
>           <web-resource-collection>
>              <web-resource-name>Success</web-resource-name>
>              <url-pattern>/welcome.jsp</url-pattern>
>              <http-method>GET</http-method>
>              <http-method>POST</http-method>
>           </web-resource-collection>
>           <auth-constraint>
>              <role-name>developers</role-name>
>           </auth-constraint>
>        </security-constraint>

>        <login-config>
>            <auth-method>BASIC</auth-method>
>            <realm-name>default</realm-name>
>        </login-config>

>        <security-role>
>           <role-name>developers</role-name>
>        </security-role>

>     </web-app>

Listing 6-4 Sample weblogic.xml File

>     <weblogic-web-app>
>        <security-role-assignment>
>           <role-name>developers</role-name>
>           <principal-name>myGroup</principal-name>
>        </security-role-assignment>
>     </weblogic-web-app>

While you can set additional security policies in the `web.xml`/`weblogic.xml` deployment descriptors and in the Administration Console, BEA recommends that you copy the security policies defined in the Web application deployment descriptors once, then use the Administration Console to define subsequent security policies. This is because any changes made to the security policies through the Administration Console during configuration of an Authorization provider will not be persisted to the `web.xml` and `weblogic.xml` files. Before you deploy the Web application again (which will happen if you redeploy it through the Administration Console, modify it on disk, or restart WebLogic Server), you should set the value of the On Future Redeploys drop-down menu to Ignore Roles and Polices From DD. If you do not, the security policies defined using the Administration Console will be overwritten by those defined in the deployment descriptors. For more information, see Using the Combined Technique to Secure Your URL (Web) and Enterprise JavaBean (EJB) Resources in Securing WebLogic Resources.

Notes: The same process applies to EJBs, but with the `ejb-jar.xml`/`weblogic-ejb-jar.xml` deployment descriptors.

The On Future Redeploys drop-down menu also affects Role Mapping providers and Credential Mapping providers. For more information, see Managing Role Mapping Providers and Deployment Descriptors and Managing Credential Mapping Providers, Resource Adapters, and Deployment Descriptors, respectively.

### Enabling Security Policy Deployment

If you implemented the `DeployableAuthorizationProvider` SSPI as part of developing your custom Authorization provider and want to support deployable security policies, the person configuring the custom Authorization provider (that is, you or an administrator) must be sure that the Policy Deployment Enabled check box in the WebLogic Server Administration Console is checked. Otherwise, deployment for the Authorization provider is considered "turned off." Therefore, if multiple Authorization providers are configured, the Policy Deployment Enabled check box can be used to control which Authorization provider is used for security policy deployment.

Note: The On Future Redeploys drop-down menu (specified at the security realm level and described in Managing Authorization Providers and Deployment Descriptors) determines whether you want security policies to be copied into the security databases for the configured Authorization providers. The Policy Deployment Enabled check box (specified for each configured Authorization provider) determines whether or not the Authorization provider is the one that stores the deployed security policy.

## Provide a Mechanism for Security Policy Management

While configuring a custom Authorization provider via the WebLogic Server Administration Console makes it accessible by applications requiring authorization services, you also need to supply administrators with a way to manage this security provider's associated security policies. The WebLogic Authorization provider, for example, supplies administrators with a Policy Editor page (see Figure 6-2) that allows them to add, modify, or remove security policies for various WebLogic resources by right-clicking on the resource and selecting the Define Security Policy... option.

Figure 6-2 WebLogic Authorization Provider's Policy Editor Page

Neither the Policy Editor page nor the right-click access to it is available to administrators when you develop a custom Authorization provider. Therefore, you must provide your own mechanism for security policy management. This mechanism must read and write security policy data (that is, expressions) to and from the custom Authorization provider's database.

You can accomplish this task in one of three ways:

- Option 1: Create Your Own "Policy Editor" Page Using Console Extensions
- Option 2: Develop a Stand-Alone Tool for Security Policy Management
- Option 3: Integrate an Existing Security Policy Management Tool into the Administration Console

### Option 1: Create Your Own "Policy Editor" Page Using Console Extensions

The main benefit of creating console extensions for your custom Authorization provider is that you automatically know the ID for the WebLogic resource and therefore, the WebLogic resource's location in the resource hierarchy. (This information is required to read and write expressions to and from the Authorization provider's database.) An additional benefit is that your page can be integrated into the existing WebLogic Server Administration Console GUI, like the Policy Editor page provided with the WebLogic Authorization provider.

If you selected this option, you need to:

1. Implement the `getExtensionForPolicy()` method of the `weblogic.management.console.extensibility.SecurityExtensionV2` interface, and have this method return your Policy Editor page.

Note: For more information, see Writing Console Extensions for Custom Security Providers.

2. In addition, you must do one of the following:

1. Implement the `PolicyEditor` and `PolicyReader` optional Authorization SSPI MBeans to develop a management MBean that will act as an intermediary between your Policy Editor page and the Authorization provider's database. For more information, see Determine Which SSPI MBeans to Extend and Implement and Table 2-4.

In this case, you also need to develop a syntax for the expressions that make up a security policy that can be respresented as a string. (For example, `Role=Admin` or `Group=Administrators`.)

Note: This syntax can be different for different Authorization providers. For more information about expressions, see Components of a Security Policy: Policy Conditions, Expressions, and Policy Statements in Securing WebLogic Resources.

2. Develop your own MBean APIs for managing security policies, and implement those interfaces to develop a management MBean that will act as an intermediary between your Policy Editor page and the Authorization provider's database.
3. Have your page read and write the expressions from and to the custom Authorization provider's database directly, without delegating to an MBean.

### Option 2: Develop a Stand-Alone Tool for Security Policy Management

You would typically select this option if you want to develop a tool that is entirely separate from the WebLogic Server Administration Console.

For this option, you do not need to write any console extensions for your custom Authorization provider, nor do you need to develop any management MBeans as described in Option 1: Create Your Own "Policy Editor" Page Using Console Extensions. However, your tool needs to:

1. Determine the WebLogic resource's ID, since it is not automatically provided to you by the console extension. For more information, see WebLogic Resource Identifiers.
2. Determine how to represent the expressions that make up a security policy. (This representation is entirely up to you and need not be a string as in Option 1: Create Your Own "Policy Editor" Page Using Console Extensions.)
3. Read and write the expressions from and to the custom Authorization provider's database.

### Option 3: Integrate an Existing Security Policy Management Tool into the Administration Console

You would typically select this option if you have a tool that is separate from the WebLogic Server Administration Console, but you want to launch that tool from the Administration Console.

For this option, your tool needs to:

1. Determine the WebLogic resource's ID, since it is not automatically provided to you by the console extension. For more information, see WebLogic Resource Identifiers.
2. Determine how to represent the expressions that make up a security policy. (This representation is entirely up to you and need not be a string as in Option 1: Create Your Own "Policy Editor" Page Using Console Extensions.)
3. Read and write the expressions from and to the custom Authorization provider's database.
4. Link into the Administration Console using basic console extension techniques, as described in Extending the Administration Console.