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

• getRoleMapper

  public RoleMapper getRoleMapper()
  

  The getRoleMapper method obtains the implementation of the RoleMapper SSPI. For a single runtime class called MyRoleProviderImpl.java, the implementation of the getRoleMapper method would be:

  return this;
  

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

  return new MyRoleMapperImpl;
  

  This is because the runtime class that implements the RoleProvider SSPI is used as a factory to obtain classes that implement the RoleMapper SSPI.

See Java API Reference for Oracle WebLogic Server for the RoleProvider SSPI.

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

• deleteApplicationRoles

  void deleteApplicationRoles(ApplicationInfo application)
  

  Deletes all roles for an application and is called only on the Administration Server within a WebLogic Server domain at the time an application is deleted.

• deployRole

  void deployRole(DeployRoleHandle handle, Resource resource, String roleName,
  String[] userAndGroupNames)
  

  Creates a role on behalf of a deployed Web application or EJB. If the role already exists, it is removed and replaced by this role.

• endDeployRoles

  void endDeployRoles(DeployRoleHandle handle)
  

  Marks the end of an application role deployment.

• startDeployRoles

  DeployRoleHandle startDeployRoles(ApplicationInfo application)
  

  Marks the beginning of an application role deployment and is called on all servers within a WebLogic Server domain where an application is targeted.

• undeployAllRoles

  void undeployAllRoles(DeployRoleHandle handle)
  

  Deletes a set of roles on behalf of an undeployed Web application or EJB.

See Java API Reference for Oracle WebLogic Server for the DeployableRoleProviderV2 SSPI.

To implement the RoleMapper SSPI, provide implementations for the following methods:

• getRoles

  public Map getRoles(Subject subject, Resource  resource, ContextHandler handler)
  

  The getRoles method returns the security roles associated with a given subject for a specified WebLogic resource, possibly using the optional information specified in the ContextHandler. For more information about ContextHandlers, see ContextHandlers and WebLogic Resources.

See Java API Reference for Oracle WebLogic Server for the RoleMapper SSPI and the getRoles methods.

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.

To implement the SecurityRole interface, provide implementations for the following methods:

• equals

  public boolean equals(Object another)
  

  The equals method returns TRUE if the security role passed in matches the security role represented by the implementation of this interface, and FALSE otherwise.

• toString

  public String toString()
  

  The toString method returns this security role, represented as a String.

• hashCode

  public int hashCode()
  

  The hashCode method returns a hashcode for this security role, represented as an integer.

• getName

  public String getName()
  

  The getName method returns the name of this security role, represented as a String.

• getDescription

  public String getDescription()
  

  The getDescription method returns a description of this security role, represented as a String. The description should describe the purpose of this security role.

If you want your custom role mapping provider to support the delivery of role collections, you must implement three interfaces:

• weblogic.security.spi.RoleConsumerFactory

• weblogic.security.spi.RoleConsumer

• weblogic.security.spi.RoleCollectionHandler

These interfaces are described in the sections that follow.

A role mapping provider implements the RoleConsumerFactory interface so that an instance of a RoleConsumer is available to the WebLogic Security Framework. The WebLogic Security Framework calls your RoleConsumerFactory implementation to obtain the provider's implementation of the role consumer.

The RoleConsumerFactory SSPI has one method, which returns your implementation of the RoleConsumer SSPI interface.

public interface RoleConsumerFactory
{
  /**
   * Obtain the implementation of the RoleConsumer
   * security service provider interface (SSPI).<P>
   *
   * @return a RoleConsumer SSPI implementation.<P>
   */
  public RoleConsumer getRoleConsumer();
}

The RoleConsumer SSPI returns a role collection handler for consumption of a role collection. It has one method, getRoleCollectionHandler(), which takes a RoleCollectionInfo implementation as an argument and returns your implementation of the RoleCollectionHandler interface.

public interface RoleConsumer
{
  /**
   * Obtain a role handler for consumption of a role collection.
   *
   * @param info the RoleCollectionInfo for the role collection.
   *
   * @return a RoleCollectionHandler or NULL which indicates
   *         that the role collection is not needed.
   *
   * @exception ConsumptionException if an error occurs
   *            obtaining the handler and the role collection cannot be consumed.
   */
  public RoleCollectionHandler getRoleCollectionHandler(
                                        RoleCollectionInfo info)
    throws ConsumptionException;
}

The WebLogic Security Framework calls the getRoleCollectionHandler() method and passes data about a role collection to a security provider as an implementation of the RoleCollectionInfo interface. (This interface implementation is provided for you, you do not have to implement it.)

You use the RoleCollectionInfo getName(), getVersion(), getTimestamp(), and getResourceTypes() methods to discover information about this role collection. You then return a RoleCollectionHandler, or NULL to indicate that the role collection is not needed.

public interface RoleCollectionInfo
{
  /**
   * Get the name of the collection.
   */
  public String getName();

  /**
   * Get the runtime version of the role.
   */
  public String getVersion();

  /**
   * Get the timestamp of the role.
   */
  public String getTimestamp();

  /**
   * Get the resource types used in the role collection.
   */
  public Resource[] getResouceTypes();
}

The RoleConsumer.getRoleCollectionHandler() method returns your implementation of the RoleCollectionHandler interface. RoleCollectionHandler has two methods: setRole() and done(). The setRole() method takes a resource, a role name, and an array of user and group names that defines what user names and group names are to be assigned to that role for the given resource.

The done() method signals the completion of the role collection.

public interface RoleCollectionHandler
{
  /**
   * Set a role for the specified resource.
   */
  public void setRole(Resource resource, String roleName, String[] userAndGroupNames)
     throws ConsumptionException;

  
  /**
   * Signals the completion of the role collection.
   */
  public void done()
     throws ConsumptionException;

}

To support the delivery of an updated role collection, all role mapping providers that support the RoleConsumer SSPI need to examine the contents of the RoleCollectionInfo passed in the RoleConsumer.getRoleCollectionHandler() method to determine if a role collection has changed. Each provider must decide (possibly by configuration) how to perform conflict resolution with the initial role collection and any customized role received outside of the SSPI.

For the WebLogic Server supplied role mapping providers, customized roles will not be replaced by the updated role collection: all roles from the initial role collection will be removed and only the customized roles, plus the updated role collection, will be in effect. If the role collection info has a different timestamp or version, it's treated as an updated role collection. The collection name is used as a persistence key.

Role mapping providers that implement the Role Consumer SSPI must also implement the weblogic.management.security.authorization.RoleConsumerMBean to indicate that the provider supports policy consumption.

The XACML 2.0 Core Specification (http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-core-spec-os.pdf) and the Oracle extensions described in Securing Resources Using Roles and Policies for Oracle WebLogic Server are the definitive sources of information for the XACML policy files used by the supplied XACML Authorization and Role Mapping Providers.

However, if as part of your development process you want to take a look at the format of a supported XACML file, perhaps the most convenient way is to use the WebLogic Server Administration Console to export the data from the XACML Authorization or Role Mapping provider's database as a XACML file. Copy this exported XACML file to a file with some other name and use the tool of your choice to review the copy.

Example 8-3 shows an example of using WLST to add a single policy to an instance of the PolicyStoreMBean from a XACML file.

The example assumes that you have defined the properties used in this script elsewhere, in a manner similar to the following lines from an ant script:

<property name="xacml-docs-dir" value="${xacmldir}/xacml-docs"/>
<sysproperty key="file" value="${xacml-docs-dir}/policy-getSubject.xacml"/>

You should avoid entering clear-text passwords in WLST commands in general, and you should especially avoid saving on disk WLST scripts that include clear-text passwords. In these instances you should use a mechanism for passing encrypted passwords instead. See Security for WLST in Understanding the WebLogic Scripting Tool.

:
try:
      protocol = System.getProperty("protocol")
      host = System.getProperty("host")
      user = System.getProperty("authuser")
      passwd = System.getProperty("authpwd")
      port = System.getProperty("port")
      dom = System.getProperty("domain")
      rlm = System.getProperty("realm")
      fil = System.getProperty("file")
      prov = System.getProperty("provider")
      stat = System.getProperty("status")

def configure():
try:
      url = protocol + "://" + host + ":" + port
      connect(user,passwd, url)
      path = "/SecurityConfiguration/" + dom + "/Realms/" + rlm + "/" + prov
      print("cd'ing to " + path)
      cd(path)
      print("calling open()")
      xacmlFile = open(fil,"r")
      print("calling read()")
      xacmlDoc = xacmlFile.read()
      print("calling cmo.addPolicy")
      if stat == "none":
          cmo.addPolicy(xacmlDoc)
      else:
          cmo.addPolicy(xacmlDoc, stat)
      print("Add error handling")
:
:

java -Dhost="localhost " -Dprotocol="t3" -Dauthuser="weblogic"
-Dauthpwd="weblogic" -Dport="7001" -Ddomain="mydomain" -Drealm="myrealm"
-Dprovider="Authorizers/XACMLAuthorizer"
-Dfile="C:/XACML/xacml-docs/policy12.xml" -Dstatus="none" weblogic.WLST
XACML/scripts/XACMLaddPolicy.py

Example 8-4 shows an example of using WLST to read a PolicySet as a string.

The example assumes that you have defined the properties used in this script elsewhere, in a manner similar to the following lines from an ant script:

<sysproperty key="identifier"
value="urn:sample:xacml:2.0:wlssecqa:resource:type@E@Fejb@G@M@Oapplication@ENoD
DRolesOrPoliciesEar@M@Omodule@Eejb11inEarMiniAppBean.jar@M@Oejb@EMiniAppBean@
M@Omethod@EgetSubject@M@OmethodInterface@ERemote"/>
<sysproperty key="version" value="1.0"/>

You should avoid entering clear-text passwords in WLST commands in general, and you should especially avoid saving on disk WLST scripts that include clear-text passwords. In these instances you should use a mechanism for passing encrypted passwords instead. See Security for WLST in Understanding the WebLogic Scripting Tool.

:
:
try:
      print("start XACMLreadPolicySet.py")
      protocol = System.getProperty("protocol")
      host = System.getProperty("host")
      user = System.getProperty("authuser")
      passwd = System.getProperty("authpwd")
      port = System.getProperty("port")
      dom = System.getProperty("domain")
      rlm = System.getProperty("realm")
      prov = System.getProperty("provider")
      id = System.getProperty("identifier")
      vers = System.getProperty("version")
:
:
def configure():
try:
      url = protocol + "://" + host + ":" + port
      connect(user,passwd, url)
      path = "/SecurityConfiguration/" + dom + "/Realms/" + rlm + "/" + prov
      print("cd'ing to " + path)
      cd(path)
      polset = cmo.readPolicySetAsString(id, vers)
      print("readPolicySetAsString() returned the following policy set: " + polset)
      print"Add error handling."
:
:

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

Because the Java EE platform standardizes Web application and EJB security in deployment descriptors, WebLogic Server integrates this standard mechanism with its Security Service to give you a choice of techniques for securing Web application and EJB resources. You can use deployment descriptors exclusively, the WebLogic Server Administration Console exclusively, or you can combine the techniques for certain situations.

Depending on the technique you choose, you also need to apply a Security Model. WebLogic supports different security models for individual deployments, and a security model for realm-wide configurations that incorporate the technique you want to use.

See Options for Securing EJB and Web Application Resources in Securing Resources Using Roles and Policies for Oracle WebLogic Server.

When configured to use deployment descriptors, WebLogic Server reads security role information from the web.xml and weblogic.xml deployment descriptor files (examples of web.xml and weblogic.xml files are shown in Example 8-5 and Example 8-6. This information is then copied into the security provider database for the role mapping provider.

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

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

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

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 role mapping provider, nor do you need to develop any management MBeans. 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 role. (This representation is entirely up to you and need not be a string.)

3. Read and write the expressions from and to the custom role mapping provider's database.

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 WebLogic Server 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. See WebLogic Resource Identifiers.

2. Determine how to represent the expressions that make up a security role. (This representation is entirely up to you and need not be a string.)

3. Read and write the expressions from and to the custom role mapping provider's database.

4. Link into the WebLogic Server Administration Console using basic console extension techniques.