9 Creating and Managing Policy Sets

Policy sets provide a means to attach policies globally to a range of endpoints of the same type. This chapter describes how to manage and create policy sets using Oracle Enterprise Manager Fusion Middleware Control and the command line interface WebLogic Scripting Tool (WLST). For information about attaching policies to policy subjects directly, see Chapter 8, "Attaching Policies to Web Services".

This chapter includes the following sections:

Notes:

The procedures in this chapter apply to Oracle Infrastructure Web Services only.

To view the help for the WLST commands described in this chapter, connect to a running instance of the server and enter help('wsmManage').

Understanding Global Policy Attachments Using Policy Sets

In addition to attaching policies directly to endpoints, you can create policy sets that allow you to attach policies globally to a range of endpoints of the same type, regardless of the deployment state. You can create and manage policy sets using both Fusion Middleware Control and the WebLogic Scripting Tool, WLST. Both methods are described in this chapter. Reference information about the WLST commands is provided in "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference

Attaching policies globally using policy sets allows an administrator to ensure that all subjects are secured in situations where the developer, assembler, or deployer did not explicitly specify the policies to be attached. For example, if the developer did not specify policies in annotations or include policy references in deployment descriptors, then the deployer must attach them or chance a potential security risk. By attaching policies globally to a set of subjects by type, the administrator can ensure that all subjects are secured by default independent of, and even prior to, deployment. The administrator can, for example, define a policy set that attaches a security policy to all Web service endpoints in a domain. In this case, any new services added to the domain automatically inherit the security configuration defined in the policy set. For more information, see "Determining the Secure Status of an Endpoint".

Policies attached globally using policy sets also provide the following:

  • The ability to specify configuration overrides on a referenced policy that apply to all endpoints to which the policy set is scoped. For information about configuring overrides, see "Overriding Configuration Properties for Globally Attached Policies".

  • The ability to specify a run-time constraint that determines the context in which the policy set is relevant. For example, you can specify that a service use message protection when communicating with external clients only since the message may be transmitted over insecure public networks. However, when communicating with internal clients on a trusted network, message protection may not be required. For more information, see "Specifying Run-time Constraints in Policy Sets".

You can disable a globally attached policy for a specific endpoint or range of endpoints using predefined policies that do not enforce any behavior that are included with your Fusion Middleware installation. When you attach one of these policies to a specific endpoint or at a lower scope, you disable the behavior of the policy that was attached globally at the higher scope. For more information, see "Disabling a Globally Attached Policy".

Policy set definitions are stored as separate XML documents in the Oracle WSM Repository under the /policysets/global directory.

Subject Types and Scope of Resources

Policy subjects to which policy sets can be attached include SOA components, SOA service endpoints, SOA references, Web services endpoints, Web service clients, Web service connections, and asynchronous callback clients. Policy sets can be attached at the following scopes:

  • Domain — all policy subjects of the specified type in a domain

  • Application or Partition—all policy subjects of the specified type in an application or SOA partition

  • Application module or SOA composite—all policy subjects of the specified type in an application module or SOA composite

  • Service or reference—all policy subjects of the specified type in a SOA service or reference

  • Port or component—all policy subjects of the specified type in a port or SOA component

For more information, see "Defining the Type and Scope of Resources".

Typical Uses for Global Policy Attachments

Typical scenarios in which attaching policies globally can be useful include:

  • All subjects of a given type need to be protected with the same set of policies, each using their default configuration. For example, all services in a domain need to be protected with authentication (using SAML or Username token) and WSS11 message protection. You can create a policy set to attach the appropriate policy to all services in the domain.

  • A subset of subjects need to be protected with the same set of policies, but these policies are different from the domain-wide default. For example, all services need to be protected with authentication (using SAML or Username token), but the General Ledger application also needs stronger WSS11 message protection. You create one policy set that attaches an authentication policy to all services, and a second policy set that attaches the stronger message protection policy to the General Ledger application.

  • A single subject needs to be protected by a policy in a category that is not already covered by the current set of global policy attachments and both policies need to be applied. For example, a highly-sensitive financials-based service endpoint requires permission for a client to access it in addition to the authentication and message protection required. In this case, directly attach the authorization policy to the financials-based service endpoint. The direct attachment is combined with the policies attached globally and both policies will be enforced.

  • An application has been deployed with design-time policy attachments and needs to convert to using global policy attachments. The migrateAttachments WLST command can be used to migrate the attachments. For more information, see "Migrating Direct Policy Attachments to Global Policy Attachments".

Navigating to the Policy Set Summary Page

You can manage your policy sets at the domain level from the Policy Set Summary page. From this page, you can view, create, copy, edit, and delete policy sets.

To navigate to the Policy Set Summary page:

  1. In the Navigator pane, expand WebLogic Domain.

  2. Select the domain for which you want to manage policy sets.

  3. From the WebLogic Domain menu, select Web Services then Policy Sets.

    The Policy Set Summary page is displayed, as shown in Figure 9-1.

    Figure 9-1 Policy Set Summary Page

    Description of Figure 9-1 follows
    Description of "Figure 9-1 Policy Set Summary Page"

Displaying a List of Policy Sets Using WLST

To display a list of the policy sets in the repository:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Use the listPolicySets command to display a list of the policy sets in the repository.

    listPolicySets ([type=None])
    

    You can limit the display to include only those policy sets that apply to a specific type of policy subject resource types. To specify the type of subject, you must use the abbreviations specified in Table 9-1, "Policy Subject Resource Types".

    For example, to display a list of policy sets that apply to Web service endpoints:

    wls:/jrfserver_domain/serverConfig>listPolicySets('ws-service')
     Global Policy Sets in Repository:
      app-only-web-service-policies
      all-domains-default-web-service-policies
    

For more information about this WLST command, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Viewing the Configuration of a Policy Set

The following sections describe how to view a policy set using either Fusion Middleware Control or the command-line interface WebLogic Scripting Tool (WLST).

Using Fusion Middleware Control

To view a policy set:

  1. Navigate to the Policy Set Summary page as described in "Navigating to the Policy Set Summary Page".

  2. In the Policy Set Summary page, select a policy set from the table and click View.

  3. When you are done viewing the policy set, click Return to Policy Sets.

    Figure 9-2 Viewing a Policy Set

    Description of Figure 9-2 follows
    Description of "Figure 9-2 Viewing a Policy Set"

Using WLST

To view the configuration of a specific policy set in the repository:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Use the displayPolicySet command to display the configuration of a specified policy set.

    displayPolicySet ([name=None])
    

    When you execute this command outside of a repository session, you can display the configuration of any policy set using the name argument. If the policy set does not exist, an error message is displayed.

    If you are creating or modifying a policy set in a repository session, you do not need to specify the name argument. The current policy set is used by default. If the policy set is being modified, then the modified version is displayed. Otherwise, the latest version in the repository is displayed.

    For example:

    wls:/jrfserver_domain/serverConfig>displayPolicySet('int-only-web-service-policies')
    
     Policy Set Details:
    -------------------
    Name:                int-only-web-services-policies
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Domain("*")
    Constraint:          !HTTPHeader("VIRTUAL_HOST_TYPE","external")
    Description:         Policies for non-external client requests
    Enabled:             true
    Policy Reference:    security : oracle/wss_saml_or_username_token_service_policy, enabled=true
                         reference.priority=1
                         management : oracle/log_policy, enabled=true
    

For more information about this WLST command, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Managing Repository Modification Sessions Using WLST

When using WLST to create, modify, and delete policy sets, you must execute the commands in the context of a repository session. Each repository session applies to a single policy set only.

To create a session in which the repository will be modified, use the beginRepositorySession command. After you have entered the desired commands to create, modify, or delete a policy set, you write the contents of the session to the repository using the commitRepositorySession command.

Use the describeRepositorySession command to describe the contents of the current session.

To exit a repository session without writing the contents to the repository, use the abortRepositorySession command.

Examples of these commands are provided in the subsequent sections. For additional information, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Creating a Policy Set

The following sections describe how to create a policy set using either Fusion Middleware Control or the command line interface WebLogic Scripting Tool, WLST.

Using Fusion Middleware Control

To create a policy set:

  1. Navigate to the Policy Set Summary page as described in "Navigating to the Policy Set Summary Page".

  2. From the Policy Set Summary page, click Create.

    The first page of the policy set creation wizard is displayed.

  3. In the Enter General Information page, as shown in Figure 9-3, enter a name for the policy set.

    Figure 9-3 Enter General Information Page

    Description of Figure 9-3 follows
    Description of "Figure 9-3 Enter General Information Page"

  4. Select the Enabled check box if you want to enable the policy set.

  5. In the Type of Resources field, select the type of policy subject to which you want to attach policies. On the next page you define the scope of resources to which you want the policy set to apply. The type of policy subjects that you can select are as follows:

    • Asynchronous Callback Client

    • REST Resource

    • SOA Component

    • SOA Reference

    • SOA Service

    • Web Service Client

    • Web Service Connection

    • Web Service Endpoint

  6. Optionally, add a description of the policy set, and click Next.

  7. In the Enter Resource Scope page, enter at least one pattern string that defines the scope for the resource type you selected in the previous step. The following resource scopes are supported:

    • Domain

    • Server Instance

      Note:

      Use of the Server Instance scope is not recommended because it can cause unreliable results.

    • SOA Partition

    • Application

    • Application Module

    • SOA Composite

    • SOA Service

    • SOA Reference

    • SOA Component

    • Port

    Note:

    To specify a resource scope, you must enter a pattern string in at least one Pattern field on this page.

    The list of available resource scopes is determined by the Resource Type you selected on the previous page. For example, if you selected Web Service Endpoint, the resource scopes available are Domain Name, Server Instance Name, Application Name, Application Module Name, SOA Service or Web Service Endpoint, Name and Port Name. For SOA Service resource types, the resource scopes available are Domain Name, Server Instance Name, SOA Partition Name, SOA Composite Name, SOA Service or Web Service Endpoint Name, and Port Name.

    For example, to attach the policies to all Web Service endpoints in the domain, enter a pattern string to represent the name of the domain only. You do not need to complete any of the other fields. To attach the policies at a finer scope, for example at the application or application module level, enter a pattern string to represent the name of the application or the module in the Pattern field. You can use an asterisk (*) as a wildcard character anywhere within the string to match any number of characters at its position; you can specify multiple wildcards within the string. Note that if you use only an asterisk wildcard for Domain, the scope level will affect all domains in the enterprise.

    If you provide a pattern string for multiple resource scopes, such as Domain Name and Application, the filtering conditions are ANDed together; for example, Domain("myDomain*") AND Application("*myApp*"). For more information about specifying the resource type and scope, and an example that specifies multiple resource scopes, see "Defining the Type and Scope of Resources".

    Figure 9-4 Enter Resource Scope Page

    Description of Figure 9-4 follows
    Description of "Figure 9-4 Enter Resource Scope Page"

  8. Click Next.

  9. In the Enter Constraint page, optionally enter a constraint to be applied to the policy set that determines the context in which the policy set is relevant. For example, you can specify that a service use message protection when communicating with external clients since the message may be transmitted over insecure public networks. However, when communicating with internal clients on a trusted network, message protection may not be required.

    To specify a constraint, in the Constraint Expression Details section of the page, select the Enabled check box, provide a header name and value in the HTTP Header Name and HTTP Header Value fields, optionally select the !(NOT) Operator to invert the constraint, and click Update Constraint. Then click Next.

    For more information about specifying a constraint, see "Specifying Run-time Constraints in Policy Sets".

  10. In the Add Policy References page, select a policy from the Available Policies list, and click Attach.

    To view details about a policy, select the policy and click the View Detail icon. A pop-up window provides a full read-only description of the policy and lists the assertions that it contains. Click OK when you are finished reviewing the details of the policy.

  11. Continue selecting and attaching policies. When you are finished, click Validate to verify that the combination of policies selected are valid.

    Figure 9-5 Add Policy References Page

    Description of Figure 9-5 follows
    Description of "Figure 9-5 Add Policy References Page"

  12. Click Next to view the Policy Set Summary Page.

  13. Review the policy set summary information. If you are satisfied with the policy set, click Save.

    Note that if the validation fails, the policy set is still saved, but in disabled mode.

    Figure 9-6 Policy Set Summary Page in Create Policy Set Wizard

    Description of Figure 9-6 follows
    Description of "Figure 9-6 Policy Set Summary Page in Create Policy Set Wizard"

Using WLST

Use the following procedure to create a policy set using WLST.

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Begin a repository session using the beginRepositorySession command.

    The beginRepositorySession command is used to create a session in which the repository will be modified. All creation, modification, or deletion commands must be performed in the context of a session. A session can only act on a single document.

    For example:

    wls:/jrfserver_domain/serverConfig> beginRepositorySession()
    
    Repository session begun.
    
  3. Use the createPolicySet command to create a new, empty policy set. The name, type, and attachTo arguments are required.

    createPolicySet(name, type, attachTo, [description=None], [enable='true'])
    

    Where:

    • name represents the name of the new, empty policy set.

    • type represents the type of policy subject to which the new policy set applies.

    • attachTo represents the scope of resources to which the policy set will be attached. This argument must use a supported expression that defines a valid resource scope in a supported format. For more information, see "Defining the Type and Scope of Resources".

      You do not need to enter the exact domain name for the resource scope. wildcards are permitted, as shown in the example. For details, see "Defining the Type and Scope of Resources".

    • description represents an optional argument that provides a description of the policy set.

    • enable specifies if the policy set is enabled or disabled. This argument is optional.

    For example, to create a policy set for all services in a domain using only the required arguments:

    wls:/jrfserver_domain/serverConfig> createPolicySet('all-domains-default-web-service-policies', 'ws-service', 'Domain("*")')
    
    Description defaulted to "Global policy attachments for Web Service Endpoint resources."The policy set was created successfully in the session.
    

    Note that because no description was specified on the command line, a default description was provided.

    For additional details about the arguments for this command, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

  4. Specify a description using the setPolicySetDescription command.

    setPolicySetDescription(description)
    

    For example, to set the description as "Default policies for web services in any domain", use the following command:

    wls:/jrfserver_domain/serverConfig> setPolicySetDescription('Default policies for web services in any domain')
    
    Description updated.
    
  5. To attach a policy to the current policy set, use the attachPolicySetPolicy command. The policy, identified by the specified URI using the uri argument, is attached to the endpoints specified in the policy set. You can repeat this command as needed to attach all the desired policies to the policy set.

    attachPolicySetPolicy(uri)
    

    For example, to attach the policy 'oracle/wss11_saml_or_username_token_with_message_protection_service_policy' to the subjects specified in the policy set, enter the following command:

    wls:/jrfserver_domain/serverConfig>attachPolicySetPolicy('oracle/wss11_saml_or_username_token_with_message_protection_service_policy')
    
    Policy reference added.
    
  6. Optionally, specify a configuration override or a run-time constraint. For details, refer to the following topics:

  7. Optionally, display the configuration of the policy set during the current repository session using the displayPolicySet command.

    displayPolicySet(name=None)
    

    Note that when you execute this command within a repository session, you do not need to specify the name argument. The current policy set is used by default. If the policy set is being modified, then the modified version is displayed. Otherwise, the latest version in the repository is displayed.

    For example:

    wls:/jrfserver_domain/serverConfig>displayPolicySet() 
    
    Policy Set Details:
    -------------------
    Name:                all-domains-default-web-service-policies
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Domain("*")
    Description:         Default policies for web services in any domain
    Enabled:             true
    Policy Reference:    security : oracle/wss11_saml_or_username_token_with_message_protection_service_policy, enabled=true
    
  8. Validate the policy set using the validatePolicySet command.

    validatePolicySet(name=None)
    

    If a name is not provided, then the command validates the policy set being created or modified in the current session. Note that you can also execute this command outside of a repository session. If you do so, the name argument is required.

    For example:

    wls:/jrfserver_domain/serverConfig> validatePolicySet()
     
    The policy set all-domains-default-web-service-policies is valid.
    
  9. Write the contents of the current repository session to the repository using the commitRepositorySession command.

    wls:/jrfserver_domain/serverConfig> commitRepositorySession()
    
    The policy set all-domains-default-web-service-policies is valid.
    Creating policy set all-domains-default-web-service-policies in repository.
     
    Repository session committed successfully.
    

    Alternately, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

For more information about these WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Creating a Policy Set from an Existing Policy Set

You can use an existing policy set as the base for a new policy set. The following sections describe how to create a new policy set from an existing policy set using either Fusion Middleware Control or the command line interface WebLogic Scripting Tool, WLST.

Note that when you create a policy set from an existing policy set, all values and attachments are copied into the new one. You can modify the resource scope and the policy attachments in the new policy set, but you cannot change the type of resource to which it applies.

Using Fusion Middleware Control

To create a policy set using an existing policy set:

  1. Navigate to the Policy Set Summary page as described in "Navigating to the Policy Set Summary Page".

  2. In the Policy Set Summary page, select the policy set that you want to copy and click Create Like.

  3. In the Enter General Information page, enter a new name and description for the policy set.

    Note the following:

    • The default new policy set name is created by appending "_Copy" to the base policy set name. For example, if the base policy set is named all-domains-default-web-service-policies, the name displayed for the copy is all-domains-default-web-service-policies_Copy.

    • The Resource Type field is read-only. When you clone a policy set, you can modify the scope but not the type of resources to which the policy set will be attached.

  4. Select or clear the Enabled check box to enable or disable the policy set.

  5. Click Next.

  6. In the Enter Resource Scope page, modify the scope as desired and click Next.

    Note:

    To specify a resource scope, a pattern string must be provided in at least one Pattern field on this page.

  7. In the Enter Constraint page, optionally specify a constraint or modify an existing constraint. Click Update Constraint, then click Next.

    For more information, see "Specifying Run-time Constraints in Policy Sets".

  8. In the Add Policy References page, modify the policy attachments as desired. When you are finished, click Validate to verify that the combination of polices selected is valid.

  9. Click Next to view the Policy Set Summary Page.

  10. Review the policy set summary information. If you are satisfied with the policy set, click Save.

Using WLST

To create a policy set from an existing policy set:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Begin a repository session using the beginRepositorySession command.

    For example:

    wls:/jrfserver_domain/serverConfig> beginRepositorySession()
    
    Repository session begun.
    
  3. Use the clonePolicySet command to create a policy set using an existing policy set.

    clonePolicySet(name, source, [attachTo=None,] [description=None], [enable='true'])
    

    Where:

    • name represents the name of the new, cloned policy set.

    • source specifies the name of the policy set to be cloned.

    • attachTo represents the scope of resources to which the policy set will be attached. This argument, if provided, must use a supported expression that defines a valid resource scope in a supported format. You do not need to enter the exact name for the resource scope. Wildcards are permitted, as shown in the example. For more information, see "Defining the Type and Scope of Resources".

      If this argument is not specified, then the expression used in the source policy set to identify the scope of resources is retained. You can also modify the resource scope using the attachPolicySet command, as described in step 5.

    • description represents an optional argument that provides a description of the cloned policy set.

    • enable specifies if the policy set is enabled or disabled. This argument is optional.

    For example, to clone a policy set:

    wls:/jrfServer_domain/serverConfig>clonePolicySet
    ('app-only-web-service-policies','all-domains-default-web-service-policies',
     None, 'Default policies for application jaxws-sut')
    
    The policy set was cloned successfully in the session.
    

    Note that the attachTo argument was not specified in this example.

    For details about the arguments for this command, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

  4. Optionally, view the configuration of the policy set using the displayPolicySet command.

    For example:

    wls:/jrfServer_domain/serverConfig> displayPolicySet()
     
    Policy Set Details:
    -------------------
    Name:                app-only-web-service-policies
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Domain("jrfServer_domain")
    Description:         Default policies for application jaxws-sut
    Enabled:             true
    Policy Reference:    security : oracle/wss11_saml_or_username_token_with_message_protection_service_policy, enabled=true
    
  5. To change the resource scope of the attachments, use the attachPolicySet command.

    attachPolicySet(expression)
    

    Where:

    • expression is a supported expression that defines the resource scope, in a supported format, that is valid for the resource type defined in the policy set. For example, for SOA resource types, you cannot define the resource scope to be an application. The supported resource scopes for SOA resource types are Domain, Server, and Composite.

      Note:

      Use of the Server scope is not recommended because it can cause unreliable results.

      For more information, see "Defining the Type and Scope of Resources".

    For example, to attach the policies in the policy set only to the application named jaxws-sut, enter the following command:

    wls:/jrfServer_domain/serverConfig> attachPolicySet('Application("jaxws-sut")')
     
    Scope of resources updated.
    
  6. Optionally, specify a configuration override or a run-time constraint. For details, refer to the following topics:

  7. Optionally, view the configuration of the cloned policy set using the displayPolicySet command.

    For example:

    wls:/jrfserver_domain/serverConfig>displayPolicySet() 
    
    Policy Set Details:
    -------------------
    Name:                app-only-web-service-policies
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Application("jaxws-sut")
    Description:         Default policies for application jaxws-sut
    Enabled:             true
    Policy Reference:    security : oracle/wss11_saml_or_username_token_with_message_protection_service_policy, enabled=true
    
  8. Write the contents of the current repository session to the repository using the commitRepositorySession command.

    For example:

    wls:/jrfserver_domain/serverConfig>commitRepositorySession()
    The policy set app-only-web-service-policies is valid.
    Creating policy set app-only-web-service-policies in repository.
     
    Repository session committed successfully.
    

    Alternately, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

For more information about these WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Editing a Policy Set

The following sections describe how to edit an existing policy set using either Fusion Middleware Control or the command line interface WebLogic Scripting Tool, WLST.

Using Fusion Middleware Control

To edit an existing policy set:

  1. Navigate to the Policy Set Summary page as described in "Navigating to the Policy Set Summary Page".

  2. In the Policy Set Summary page, select the policy set that you want to edit and click Edit.

  3. In the Enter General Information page, select or clear the Enabled check box to enable or disable the policy set. You can also edit the policy set description.

    Note that the Name and Type of Resources fields are read-only.

  4. Click Next.

  5. In the Enter Resource Scope page, modify the scope as desired and click Next.

  6. In the Enter Constraint page, optionally specify a constraint or modify an existing constraint. Click Update Constraint, then click Next.

    For more information about specifying a constraint, see "Specifying Run-time Constraints in Policy Sets".

  7. In the Add Policy References page, modify the policy attachments as desired. When you are finished, click Validate to verify that the combination of polices selected is valid.

  8. Click Next to view the Policy Set Summary Page.

  9. Review the policy set summary information. If you are satisfied with the policy set, click Save.

Using WLST

To edit a policy set:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Begin a repository session using the beginRepositorySession command.

    For example:

    wls:/jrfserver_domain/serverConfig> beginRepositorySession()
    
    Repository session begun.
    
  3. Use the modifyPolicySet command to select an existing policy set to edit.

    modifyPolicySet(name)
    

    The latest version of the named policy set will be loaded into the current session. For example, to edit a policy set to add policies, use the following command:

    wls:/jrfServer_domain/serverConfig> modifyPolicySet('all-domains-default-web-service-policies')
     
    The policy set is ready for modification in the session.
    
  4. Edit the policy set as desired. For example:

    • To add policies to the policy set, use the attachPolicySetPolicy command, identifying the policy by a specified URI using the uri argument.

      attachPolicySetPolicy(uri)
      

      To add the oracle/wss_saml_or_username_token_service_policy and the oracle/log_policy policies to the policy set, enter the following commands:

      wls:/jrfServer_domain/serverConfig> attachPolicySetPolicy('oracle/wss_saml_or_username_token_service_policy')
      
      Policy reference added.
      
      wls:/jrfServer_domain/serverConfig>attachPolicySetPolicy('oracle/log_policy')
      
      Policy reference added.
      
    • To remove policies from the policy set, use the detachPolicySetPolicy command, identifying the policy by a specified URI using the uri argument.

      detachPolicySetPolicy(uri)
      

      To remove the oracle/wss11_saml_or_username_token_with_message_protection_service_policy from the policy set, enter the following:

      wls:/jrfServer_domain/serverConfig> detachPolicySetPolicy('oracle/wss11_saml_or_username_token_with_message_protection_service_policy')
      
      Policy reference removed.
      
    • To enable or disable a policy attachment in the policy set, use the enablePolicySetPolicy command, identifying the policy by a specified URI using the uri argument.

      enablePolicySetPolicy(uri,[enable=true])
      

      The default is true.

      To disable the oracle/log_policy, enter the following:

      wls:/jrfServer_domain/serverConfig> enablePolicySetPolicy('oracle/log_policy',false)
      
      Policy reference disabled.
      
  5. Optionally, specify a configuration override or a run-time constraint. For details, refer to the following topics:

  6. Validate the policy set using the ValidatePolicySet command.

    For example:

    wls:/jrfServer_domain/serverConfig> validatePolicySet()
     
    The policy set app-only-web-service-policies is valid.
    
  7. Optionally, display the modified policy set using the displayPolicySet command.

    wls:/jrfServer_domain/serverConfig>displayPolicySet()
    
    Policy Set Details:
    -------------------
    Name:                all-domains-default-web-service-policies
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Domain("*")
    Description:         Default policies for web services in any domain
    Enabled:             true
    Policy Reference:    security : oracle/wss_saml_or_username_token_service_policy, enabled=true
                         management : oracle/log_policy, enabled=false
    
  8. To write the contents of the current repository session to the repository, use the commitRepositorySession command.

    wls:/jrfServer_domain/serverConfig> commitRepositorySession()
     
    The policy set all-domains-default-web-service-policies is valid.
    Updating policy set all-domains-default-web-service-policies in repository.
     
    Repository session committed successfully.
    

    Alternately, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Defining the Type and Scope of Resources

The resource type, or subject type, identifies the type of endpoint to which the policy set applies. It is mapped to the appliesTo attribute of the policy set.

The resource scope expression identifies the set of policy subjects to which the policy set is attached (which can be zero, one, or many). It is mapped to the attachTo attribute of the policy set. and is used for conflict resolution when multiple policy sets exist. For details about conflict resolution in policy sets, see "How the Effective Set of Policies is Calculated".

To attach policies globally across a set of resources, you must specify the type of policy subjects to which the policy set applies and the scope of resources within the topology of the enterprise.

Resource Type

In Fusion Middleware Control, you select the resource type from a menu when you are creating a policy set. When you create a policy set using WLST, you must use specific abbreviations for these resource types. Table 9-1 lists the type of resources that you select in Fusion Middleware Control, the abbreviations that are required in WLST, and the resource scopes that are valid for each resource type.

Note:

Use of the Server Instance scope is not recommended because it can cause unreliable results, especially in applications that are targeted to multiple servers, including clusters.

Table 9-1 Policy Subject Resource Types

Fusion Middleware Control
WLST Valid Resource Scope

Asynchronous Callback Client

ws-callback

  • Domain

  • Application

  • Application Module

  • Web Service Endpoint

  • Port

REST Resource

rest-resource

  • Domain

  • Application

  • Module

  • Service

Note: Server Instance is not a valid resource scope for RESTful resources.

SOA Component

sca-component

  • Domain

  • SOA Partition

  • SOA Composite

  • SOA Component

SOA Reference

sca-reference

  • Domain

  • SOA Partition

  • SOA Composite

  • SOA Reference

  • Port

SOA Service

sca-service

  • Domain

  • SOA Partition

  • SOA Composite

  • SOA Service

  • Port

Web Service Client

ws-client

  • Domain

  • Application

  • Application Module

  • Web Service Client

  • Port

Web Service Connection

ws-connection

  • Domain

  • Application

  • Application Module

  • SOA Reference or Web Service Client

  • Port

Web Service Endpoint

ws-service

  • Domain

  • Application

  • Application Module

  • Web Service Endpoint

  • Port


Resource Scope

In Fusion Middleware Control, you specify the scope by entering a pattern string that represents the name associated with the resource scope. For example, to attach a policy set to all Web service endpoints in a domain, you enter a pattern that represents the name of the domain in the Domain Name field.When specifying the resource scope in WLST, you need to use a supported expression for each scope. The supported expressions are described in Table 9-2. These expressions are required for the following arguments:

  • attachTo argument of the createPolicySet and clonePolicySet commands

  • expression argument of the attachPolicySet command

For both Fusion Middleware Control and WLST, you can enter the complete name, or a partial value using wildcards. An asterisk (*) is permitted as a wildcard character anywhere within the string to match any number of characters at its position. You can specify multiple wildcards at any position within the string. For example, for the domain name jrf_domain, you can enter jrf*, or *rf*domain, or any number of combinations. You need to provide only a single pattern for a scope. If you do not specify a pattern string for a resource scope, asterisk (*) is assumed. You can use single or double quotes. If multiple values are provided, then all of the expressions must match for the policy set to be considered attached to the policy subject.

The following is a list of the supported expressions for the resource scope.

Table 9-2 Supported Expressions for the Resource Scope

Supported Expression Description

Domain("expression")

This value will be matched against a policy subject based on the management domain in which it is deployed.

Server("expression")

This value will be matched against a policy subject based on the server instance in which it is deployed.

Note: Use of this scope is not recommended because it can cause unreliable results, especially in applications that are targeted to multiple servers, including clusters.

Application("expression")

This value will be matched against a policy subject based on the name of the application in which it is located.

Partition('expression")

This value will be matched against a policy subject based on the name of the partition in which it is located.

Module("expression")

This value will be matched against a policy subject based on the name of the application module in which it is located.

Composite("expression")

This value will be matched against a policy subject based on the name of the SOA composite in which it is located.

Note: For a composite, the expression should use the composite name only, for example:

Composite("*Basic_SOA_Client*")

Do not include the SOA partition or composite revision number in the expression.

Reference("expression")

This value will be matched against a policy subject based on the name of the reference in which it is located.

Service("expression")

This value will be matched against a policy subject based on the name of the service in which it is located.

Note: For Web Service Endpoint and Web Service Client resource types (ws-service and ws-client), the expression must include the namespace and the service name, for example:

Service("{http://mynamespace/}myService")

For applications assembled prior to PS5, the namespace is not displayed in the listWebServices output or in Fusion Middleware Control where the service name is displayed. In this case, you can determine the namespace as described in "Determining the Namespace for a Web Service".

Component("expression")

This value will be matched against a policy subject based on the name of the component in which it is located.

Port("expression")

This value will be matched against a policy subject based on the name of the port in which it is located.


Determining the Namespace for a Web Service

For applications assembled prior to PS5, the namespace is not displayed with the service name in the output for WLST commands, or in Fusion Middleware Control where the service name is displayed. To specify a service as a resource scope for Web Service Endpoints and Web Service Client resource types (ws-service and ws-client), you need to include the namespace with the service name. You can determine the namespace for a service from the Web service WSDL document. To do so:

  1. Display the WSDL document for the Web service endpoint as described in "Displaying the Web Service WSDL Document".

  2. In the WSDL document, locate the wsdl:definitions element, which includes the target namespace for the service.

    For example, in the TestService WSDL:

    http://host:7001/jaxws-service/TestService?WSDL
    

    The following wsdl:definitions element is included:

    <wsdl:definitions name="TestService"targetNamespace="http://service.jaxws.wsm.oracle/">
    

To specify a complete service name, combine the namespace with the service name. Using the example above, the complete service name is as follows:

{http://service.jaxws.wsm.oracle/}TestService

Examples

The following examples demonstrate how to create policy sets using different resource types and scopes.

Example 9-1 creates a policy set for an asynchronous callback client (ws-callback) resource type. In this example, the policy set is attached at a specific application scope, and applies to all services that satisfy the filter condition (Domain AND Application).

Example 9-1 Asynchronous Callback Client Resource Type Policy Set

beginRepositorySession()
createPolicySet('Async callback client', 'ws-callback',
 'Domain('FinancialDomain') and Application('Expense*')',
'Global policy for asynchronous callback client', true)
attachPolicySetPolicy('oracle/wss10_saml_token_client_policy')
validatePolicySet()
commitRepositorySession()
displayPolicySet('Async callback client')

Example 9-2 creates a policy set named web_connection_cost_service for a Web service connection (ws-connection) resource type. In this example, the policy set is attached at a specific application module scope, and applies to all services that satisfy the filter condition (Domain AND Application AND Module).

Example 9-2 Web Service Connection Resource Type Policy Set

beginRepositorySession()
createPolicySet('web_connection_cost_service', 'ws-connection',
 'Domain("SCMDomain") and and Application("ScmCst*") and Module("*Costs")', enable=true)
attachPolicySetPolicy('oracle/wss10_saml_token_client_policy')
validatePolicySet()
commitRepositorySession()
displayPolicySet('web_connection_cost_service')

Validating a Policy Set

In addition to validating that the policy set adheres to the rules described in "Validating Policy Subjects", policy set validation also performs the following checks:

  • Validates that the defined resource type and scope is valid for the policy set

  • Validates that the value entered for the resource scope contains a supported expression in a supported format

  • Validates that any referenced policies are available and compatible with each other. For example, the policies are compatible if their categories are not in conflict with each other.

Note:

To ensure there are no conflicts between policy attachments, you can use Fusion Middleware Control and WLST commands to determine if Web service endpoints contain a valid and secure configuration. For more information, see "Determining the Secure Status of an Endpoint".

For troubleshooting information, see "Diagnosing Policy Attachment Issues Using WLST".

Overriding Configuration Properties for Globally Attached Policies

If a policy referenced in a policy set contains overridable properties, you can override the existing value of the property for that policy set using either Fusion Middleware Control or WLST.

Using Fusion Middleware Control

To override a configuration property in a policy referenced in a policy set:

  1. Go to the Policy Set Summary page as described in "Navigating to the Policy Set Summary Page".

  2. From the Policy Set Summary page, select the policy set containing the policy for which you want to configure overrides.

    If the policy set references policies with overridable properties, the Override Policy Configuration button is displayed, as shown in Figure 9-7.

    Figure 9-7 Policy Set Override Policy Configuration Button

    Description of Figure 9-7 follows
    Description of "Figure 9-7 Policy Set Override Policy Configuration Button"

  3. Select Override Policy Configuration.

    The Override Policy Configuration page is displayed, as shown in Figure 9-8.

    Figure 9-8 Policy Set Override Policy Configuration Page

    Description of Figure 9-8 follows
    Description of "Figure 9-8 Policy Set Override Policy Configuration Page"

  4. In the Policy References table, select the policy for which you want to override the configuration property. If the policy contains overridable properties, the Override Policy Configuration button is displayed.

  5. Select Override Policy Configuration. The Security Configuration Details page is displayed, containing a list of the configuration properties that can be overridden in the selected policy.

    Figure 9-9 shows the overridable properties for the oracle/wss11_saml_or_username_token_with_message_protection_service_policy.

    Figure 9-9 Policy Set Security Configuration Details Page

    Description of Figure 9-9 follows
    Description of "Figure 9-9 Policy Set Security Configuration Details Page"

  6. Enter the override value in the Value field for the property and click Apply.

    The property will be overridden for all endpoints to which the policy set applies.

For more information about configuration overrides and the properties that can be overridden, see the following sections:

Using WLST

You can specify a configuration override in a policy referenced in a policy set using the setPolicySetPolicyOverride command. This command can be used only during the creation or modification of a policy set within the context of a repository session. The following procedure describes how to specify a configuration override while editing an existing policy set, but you can also use this command in a repository session while creating a new policy set or creating a policy set from an existing policy set.

  1. Begin a repository session using the beginRepositorySession command.

    For example:

    wls:/jrfserver_domain/serverConfig> beginRepositorySession()
    
    Repository session begun.
    
  2. Use the modifyPolicySet command to select an existing policy set to edit.

    modifyPolicySet(name)
    

    The latest version of the named policy set will be loaded into the current session. For example, enter the following command:

    wls:/jrfServer_domain/serverConfig> modifyPolicySet('all-domains-default-web-service-policies')
     
    The policy set is ready for modification in the session.
    
  3. Optionally, view the configuration of the policy set using the displayPolicySet command.

    For example:

    wls:/jrfserver_domain/serverConfig>displayPolicySet() 
    
    Policy Set Details:
    -------------------
    Name:                all-domains-default-web-service-policies
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Domain("*")
    Description:         Default policies for web services in any domain
    Enabled:             true
    Policy Reference:    security : oracle/wss_saml_or_username_token_service_policy, enabled=true
                         management : oracle/log_policy, enabled=false
    
  4. Specify the configuration override using the setPolicySetPolicyOverride command.

    For example, to specify a configuration override for the reference.priority property, enter the following command:

    wls:/jrfserver_domain/serverConfig>setPolicySetPolicyOverride('oracle/wss_saml_or_username_token_service_policy',
    'reference.priority','1')
    
    The configuration override property "reference.priority" having value "1" has
    been added to the reference to policy with URI "oracle/wss_saml_or_username_token_service_policy".
    
  5. Optionally, view the configuration of the policy set.

    For example:

    wls:/jrfserver_domain/serverConfig>displayPolicySet() 
    
    Policy Set Details:
    -------------------
    Name:                all-domains-default-web-service-policies
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Domain("*")
    Description:         Default policies for web services in any domain
    Enabled:             true
    Policy Reference:    security : oracle/wss_saml_or_username_token_service_policy, enabled=true
                         reference.priority=1
                         management : oracle/log_policy, enabled=false
    

    Note that the reference.priority configuration override is now shown in the output (in bold in the above example.)

  6. Validate the policy set using the ValidatePolicySet command.

    For example:

    wls:/jrfServer_domain/serverConfig> validatePolicySet()
     
    The policy set all-domains-default-web-service-policies is valid.
    
  7. To write the contents of the current repository session to the repository, use the commitRepositorySession command.

    wls:/jrfServer_domain/serverConfig> commitRepositorySession()
     
    The policy set all-domains-default-web-service-policies is valid.
    Updating policy set all-domains-default-web-service-policies in repository.
     
    Repository session committed successfully.
    

Specifying Run-time Constraints in Policy Sets

Applications can be deployed into environments that expose the same services to both external and internal clients. In these environments, it is often desirable to enforce different security behaviors based on where the client is located.

For example, in an environment consisting of a single Fusion Middleware server (WebLogic Server) hosting Web services, Oracle HTTP Server is configured at the front end to listen for HTTP requests from two separate networks. One of these networks is used to transport all private internal requests, while the other network is used to transport all external requests. Access via the external network is through a firewall. Since physical access to the internal network is highly restricted, requests from this network are already protected. Therefore, it is only necessary to enforce authentication and authorization. By not enforcing message protection, the load on the server is reduced and performance is increased. However, all requests from the external network are considered to be insecure since it can be potentially accessed by anyone. In this case, in addition to authentication and authorization, message protection (confidentiality and integrity) must be enforced. Performance for these requests will be lower, but is considered acceptable since the alternatives (such as data leaks, replay attacks, and so on) are far worse.

To ensure that a policy set is applied appropriately for an external network, the administrator needs to specify a constraint expression against which the policy set is evaluated. The value of the expression indicates the runtime context for which the policy set is relevant.

The constraint expression must specify a valid header name and value. The following expressions are certified in this release:

  • HTTPHeader("VIRTUAL_HOST_TYPE","External")—Sets the constraint as external and indicates that the policy set should apply to all external requests received through Oracle HTTP Server.

  • !HTTPHeader("VIRTUAL_HOST_TYPE","External")—Sets the constraint as NOT external and indicates that the policy set should apply to all incoming requests not received through Oracle HTTP server, such as those from an internal network.

Note:

The run-time constraint function HTTPHeader is only certified to use when Oracle HTTP Server is configured at the front end and the Oracle HTTP Server administrator has added a custom VIRTUAL_HOST_TYPE header to the request. For details about adding the header to the request, see "Configuring Oracle HTTP Server to Specify Request Origin". Although that procedure refers to the oracle/whitelist_authorization_policy, it also applies to specifying the request origin for run-time constraints.

When specifying constraints, the following rules apply:

  • If multiple policy sets specify the same constraint, standard effective policy calculation rules apply. For details about the standard effective policy rules, see "How the Effective Set of Policies is Calculated".

  • If multiple policy sets specify different constraints, the effective set of policies is calculated against each type of constraint independently. That is, the effective set of policies is evaluated for all external requests and a separate effective set of policies is evaluated against all non-external requests.

  • If no run-time constraint is specified in a policy set, it applies to all requests; that is, both external and non-external requests.

Figure 9-10 illustrates the effective policies for external and non-external requests determined using constraints in three different policy sets.

Figure 9-10 Effective Policy Calculation for Policy Sets with Run Time Constraints

Description of Figure 9-10 follows
Description of "Figure 9-10 Effective Policy Calculation for Policy Sets with Run Time Constraints"

Using Fusion Middleware Control

You can specify a run-time constraint when you are creating, editing, or cloning a policy set using the policy set wizard. After you specify the scope for the policy set, the Enter Constraint page is displayed. If you are editing or cloning a policy set with a constraint specified, the constraint currently configured in the policy set is displayed, as shown in Figure 9-11. If you are creating a new policy set, these fields are blank.

Figure 9-11 Enter Constraint Page in Policy Set Wizard

Description of Figure 9-11 follows
Description of "Figure 9-11 Enter Constraint Page in Policy Set Wizard"

To specify a constraint:

  1. In the Constraint Expression Details section of the page, select the Enabled check box to enable the constraint.

  2. Optionally, select the !(NOT) Operator to invert the constraint.

  3. Enter a header name and header value for the HTTPHeader constraint function in the HTTP Header Name and HTTP Header Value fields, respectively. If the constraint is enabled, the HTTP Header Name field is required.

    For example, as shown in Figure 9-11, to specify a constraint that applies to external clients only, enter VIRTUAL_HOST_TYPE in the HTTP Header Name field and External in the HTTP Header Value field.

  4. Click Update Constraint.

    The constraint expression is displayed in the Constraint field, for example HTTPHeader('VIRTUAL_HOST_TYPE','External').

Using WLST

You can specify a constraint in a policy set using the setPolicySetConstraint command. This command can be used only during the creation or modification of a policy set within the context of a repository session.

The following procedure describes how to specify a run-time constraint while creating a new policy set, but you can also use the setPolicySetConstraint command in a repository session while editing an existing policy set or creating a new policy set from an existing policy set.

  1. Begin a repository session using the beginRepositorySession command.

    For example:

    wls:/jrfServer_domain/serverConfig> beginRepositorySession()
    
    Repository session begun.
    
  2. Use the createPolicySet command to create a new policy set.

    For example, to create a policy set for that provides authentication and message protection to external clients at the domain scope:

    wls:/jrfServer_domain/serverConfig>createPolicySet('domainExternal',
    'ws-service','Domain("*")','Authentication and message protection at domain scope for external clients')
    
    The policy set was created successfully in the session.
    

    For details about creating a policy set using WLST, see "Using WLST" in "Creating a Policy Set".

  3. Attach a policy to the current policy set using the attachPolicySetPolicy command.

    For example, to attach the policy 'oracle/wss10_message_protection_service_policy' to the subjects specified in the policy set, enter the following command:

    wls:/jrfServer_domain/serverConfig>attachPolicySetPolicy('oracle/wss11_saml_or_username_token_with_message_protection_service_policy
    
    Policy reference added.
    
  4. Specify a run-time constraint using the setPolicySetConstraint(constraint) command. The constraint argument must use a supported expression that defines a valid run-time constraint in a supported format. The following expressions are certified in this release:

    • HTTPHeader("VIRTUAL_HOST_TYPE","External")

    • !HTTPHeader("VIRTUAL_HOST_TYPE","External")

    For example, to specify a constraint that applies to external clients only, enter the following command:

    wls:/jrfServer_domain/serverConfig>setPolicySetConstraint('HTTPHeader("VIRTUAL_HOST_TYPE","External")')
    
    Constraint updated.
    
  5. Optionally, display the configuration of the policy set during the current repository session using the displayPolicySet command.

    For example:

    wls:/jrfServer_domain/serverConfig>displayPolicySet() 
    
    Policy Set Details:
    -------------------
    Name:                domainExternal
    Type of Resources:   Web Service Endpoint
    Scope of Resources:  Domain("em_domain")
    Constraint:          HTTPHeader("VIRTUAL_HOST_TYPE","External")
    Description:         Authentication and message protection at domain scope for external clients
    Enabled:             true
    Policy Reference:    security : oracle/wss11_saml_or_username_token_with_message_protection_service_policy, enabled=true
    
  6. Write the contents of the current repository session to the repository using the commitRepositorySession command.

    wls:/jrfServer_domain/serverConfig> commitRepositorySession()
    
    The policy set domainMsgExternal is valid.
    Creating policy set domainMsgExternal in repository.
    Repository session committed successfully.
    

Disabling a Globally Attached Policy

To explicitly disable a globally attached policy for specific endpoints, predefined policies that do not enforce any behavior are included with your Fusion Middleware installation. You can disable a globally, or externally, attached policy by attaching one of these predefined policies that contains the same category of assertions as the policy to be disabled. You can attach the no behavior policy either directly to an endpoint, or globally at a lower scope, such as at the application or module level. By default, a policy that is directly attached takes precedence over a policy that is globally attached and a policy that is globally attached at a lower scope takes precedence over a policy that is globally attached at a higher scope. For more information, see "How the Effective Set of Policies is Calculated".

For example, if an authentication policy is globally attached to all service endpoints in a domain, you can disable it for a specific Web service endpoint by directly attaching the oracle/no_authentication_service_policy to the endpoint. Alternatively, to disable the authentication policy for only an application in the domain, you can create a policy set that attaches the oracle/no_authentication_service_policy only to the service endpoints in the application.

Note:

If the globally attached policy that you are disabling contains any other assertions, those assertions are disabled also. For example, if the global policy to be disabled is oracle/wss10_saml_token_with_message_protection_client_policy and you attach the no behavior oracle/no_authentication_service_policy to an endpoint at lower scope (or directly), both the authentication and the message protection assertions of the globally attached policy are disabled.

For details about directly attaching a policy to an endpoint, see "Attaching a Policy to a Single Subject". For more information about the no behavior policies, see "No Behavior Policies".

Note:

Do not delete these no behavior policies. All of the policies use the same no_behavior assertion. An assertion template is not provided, therefore if you delete the policies, there is no way to recreate them manually. If they are deleted by mistake, the only way to restore them is to rebuild the repository. For more information, see "Rebuilding the Oracle WSM Repository".

Enabling and Disabling a Policy Set

The following sections describe how to enable or disable a policy set using either Fusion Middleware Control or the command line interface WebLogic Scripting Tool, WLST.

Using Fusion Middleware Control

To enable or disable a policy set using Fusion Middleware Control, edit the policy set as described in "Editing a Policy Set". To enable the policy set if it is disabled, select the Enabled check box. To disable the policy set, clear the Enabled check box.

Note that you must click Next through the remaining steps, then click Save to save the updated policy set.

Figure 9-12 Enabling and Disabling a Policy Set

Description of Figure 9-12 follows
Description of "Figure 9-12 Enabling and Disabling a Policy Set"

Using WLST

To enable or disable a policy set:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Begin a repository session using the beginRepositorySession command.

    For example:

    wls:/jrfserver_domain/serverConfig> beginRepositorySession()
    
    Repository session begun.
    
  3. Specify the policy set to be modified using the modifyPolicySet command.

    For example:

    wls:/jrfServer_domain/serverConfig> modifyPolicySet('all-domains-default-web-service-policies')
     
    The policy set is ready for modification in the session.
    
  4. Use the enablePolicySet command to enable or disable a policy set.

    enablePolicySet([enable=true])
    

    Set the enable argument to true to enable a policy set if it is disabled. The default is true. Set the enable argument to false to disable a policy set.

    For example, to disable a policy set:

    wls:/jrfServer_domain/serverConfig> enablePolicySet(false)
     
    Policy set disabled.
    
  5. Validate the policy set using the ValidatePolicySet command.

    For example:

    wls:/jrfServer_domain/serverConfig> validatePolicySet()
     
    The policy set app-only-web-service-policies is valid.
    
  6. To write the contents of the current repository session to the repository, use the commitRepositorySession command.

    wls:/jrfServer_domain/serverConfig> commitRepositorySession()
     
    The policy set all-domains-default-web-service-policies is valid.
    Updating policy set all-domains-default-web-service-policies in repository.
     
    Repository session committed successfully.
    

    Alternately, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Deleting Policy Sets

The following sections describe how to delete policy sets using Fusion Middleware Control or the command line interface WebLogic Scripting Tool, WLST.

Using Fusion Middleware Control

To delete a policy set:

  1. Navigate to the Policy Set Summary page as described in "Navigating to the Policy Set Summary Page".

  2. In the Policy Set Summary page, select a policy set from the table and click Delete.

  3. A dialog box displays asking you to confirm the deletion. Click OK.

Using WLST

You can use the following commands to delete policy sets in the repository:

  • deletePolicySet—Deletes an individual policy set within the context of a repository session.

  • deleteAllPolicySets—Delete select or all policy sets in the repository. This command can be used inside or outside a repository session.

To delete an individual policy set in a repository session:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Begin a repository session using the beginRepositorySession command.

    For example:

    wls:/jrfserver_domain/serverConfig> beginRepositorySession()
    
    Repository session begun.
    
  3. Optionally, list the policy sets in the repository using the listPolicySets command.

    wls:/jrfServer_domain/serverConfig> listPolicySets()
     
    Global Policy Sets in Repository:
      app-only-web-service-policies
      all-domains-default-web-service-policies
    
  4. Delete the desired policy set using the deletePolicySet command.

    deletePolicySet (name)
    

    For example:

    wls:/jrfServer_domain/serverConfig> deletePolicySet('app-only-web-service-policies')
     
    The policy set was deleted successfully in the session.
    
  5. To write the contents of the current repository session to the repository, use the commitRepositorySession command.

    wls:/jrfServer_domain/serverConfig> commitRepositorySession()
     
    Deleting policy set app-only-web-service-policies from repository.
     
    Repository session committed successfully.
    

    Alternately, you can choose to cancel any changes by using the abortRepositorySession command, which discards any changes that were made to the repository during the session.

To delete all or select policy sets in the repository:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Optionally, list the policy sets in the repository using the listPolicySets command.

    wls:/jrfServer_domain/serverConfig> listPolicySets()
     
    Global Policy Sets in Repository:
      all-domains-default-web-service-policies
      ws-1
      ws-2
    
  3. Delete the desired policy sets using the deleteAllPolicySets() command. You can specify whether to force deletion of all the policy sets (using the force argument), or prompt to select individual policy sets for deletion. This command defaults to prompt mode.

    deleteAllPolicySets(mode)
    

    For example, to specify the policy sets to be deleted:

    wls:/jrfServer_domain/serverConfig> deleteAllPolicySets()
    
    Starting Operation deleteAllPolicySets ...
    Policy Set Name: ws-2
    Select "ws-2" for deletion (yes/no/cancel)? yes
    Policy Set Name: all-domains-default-web-service-policies
    Select "all-domains-default-web-service-policies" for deletion (yes/no/cancel)? no
    Policy Set Name: ws-1
    Select "ws-1" for deletion (yes/no/cancel)? yes
    
    All the selected policy sets were deleted successfully from repository.
    
    deleteAllPolicySets Operation Completed. 
    

    To force the deletion of all policy sets:

    wls:/jrfServer_domain/serverConfig> deleteAllPolicySets('force')
     
    Starting Operation deleteAllPolicySets ...
     
     
    All policy sets were deleted successfully from repository.
     
    deleteAllPolicySets Operation Completed. 
    

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Migrating Direct Policy Attachments to Global Policy Attachments

You can use the migrateAttachments WLST command to migrate direct (local) policy attachments to external global policy attachments if they are identical. Migrating identical policy attachments improves manageability by reducing the number of physical attachments that need to be maintained. A direct policy attachment is identical if its URI is the same as one provided by a global policy attachment, and if it does not have any configuration overrides. You cannot migrate the following:

  • Programmatic policy attachments.

  • Direct or global policy attachments to SOA components

Notes:

A direct attachment with an unscoped override will be migrated but an attachment with a scoped override will not. This is because after running the migrateAttachments command, the enforcement of the policies on all subjects remains the same, even though some policies are globally attached.

To migrate policy attachments:

  1. Connect to the running instance of WebLogic Server as described in "Accessing the Web Services Custom WLST Commands".

  2. Migrate the attachments using the migrateAttachments command. You can specify whether to force the migration (force), prompt for confirmation before each migration (prompt), or simply list the migrations that would occur (preview). If no mode is specified, the default is prompt.

    migrateAttachments(mode=None)
    

    For example, to prompt, by default, for confirmation of each potential attachment migration, enter the following command. Note in the output that there are identical global and direct policy attachments for the jaxws-sut application that can be migrated.

    wls:/jrfServer_domain/serverConfig> migrateAttachments()
     
    --------------------------------------------------------------------------------
    Application Path:    /jrfServer_domain/jrfServer/jaxws-sut-no-policy
    Web Service Name:    TestService
    Module Type:         web
    Module Name:         jaxws-service
    Port:                TestPort
     
    --------------------------------------------------------------------------------
    Application Path:    /jrfServer_domain/jrfServer/jaxws-sut
    Web Service Name:    TestService
    Module Type:         web
    Module Name:         jaxws-sut-service
    Port:                TestPort
    Policy Reference:    management : oracle/log_policy, enabled=true
                         security : oracle/wss_username_token_service_policy, enabled=true
                         (global) /policysets/global/migrate_example : oracle/wss_username_token_service_policy
     
    Migrate "oracle/wss_username_token_service_policy" (yes/no/cancel)? yes
    "oracle/wss_username_token_service_policy" was migrated successfully.
    

    For more information about the arguments for this command, see "Web Services Custom WLST Commands" in WebLogic Scripting Tool Command Reference.

Specifying the Priority of a Policy Attachment

The predefined policies provided in your installation include a configuration override, reference.priority, that allows an administrator to indicate a preference over which policy attachment is used. By default, an attached policy has a reference.priority of 0 if no other value has been specified.

For example, an administrator can globally attach a policy at the domain scope and specify a reference priority of 1 or greater to ensure that it takes precedence over any directly attached policies, without having to modify the direct attachments. If the administrator wants to make an exception for a particular direct attachment, then they can specify a reference priority for that attachment to elevate its priority above that of the global policy attachment. The policy attachment with the highest integer value for reference.priority takes precedence in the effective policy calculation, regardless of whether it is directly or externally attached, or its scope.

The value of reference.priority can be specified as follows:

  • String values "true", "yes" and "on".

    These string values are equivalent to integer value 1. Any other string values will be treated as integer value 0.

  • Integer values within the following range

    • MAX_VALUE = 2147483647 or (231 - 1)

    • MIN_VALUE = -2147483648 or (-231)

For more information, see the following topics:

Determining the Secure Status of an Endpoint

Global policy attachments provide the ability to adhere to a "secure by default" philosophy in which all subjects are secured even if the developer, assembler or deployer did not explicitly specify the policies to be attached. That is, using a policy set the administrator can ensure that one or more policies are automatically applied if none are explicitly attached.

An administrator can determine if all subjects in a domain are secure, and if the endpoint configuration is valid, using both WLST and Fusion Middleware Control.

Note the following:

  • An endpoint is considered secure if the policies attached to it (either directly or globally) enforce authentication, authorization, or message protection behaviors. A disabled policy or a disabled assertion within a policy does not enforce anything.

  • An endpoint has a valid configuration if there is no conflict in the combination of attached policies according to the effective set of policies calculation. For more information, see "How the Effective Set of Policies is Calculated"

Because you can specify the priority of a globally or directly attached policy, as described in "Specifying the Priority of a Policy Attachment", the Effective field for a directly attached policy indicates if it is in effect for the endpoint. Note that to simplify endpoint management, all directly attached policies are shown in the output regardless of whether they are in effect. In contrast, only globally attached policies that are in effect for the endpoint are displayed.

Using Fusion Middleware Control, you can view whether the configuration is valid and if the endpoint is secure on the Web Service Endpoint page. Figure 9-13 shows a valid configuration with a secure endpoint.

Figure 9-13 Web Service Endpoint Page With Valid and Secure Endpoint Configuration

Description of Figure 9-13 follows
Description of "Figure 9-13 Web Service Endpoint Page With Valid and Secure Endpoint Configuration"

Using WLST, you can generate a list of endpoints and their secured status using the listWebServices and listWebServiceClients WLST commands. The output from these commands, when the detail argument is set to true as shown in Example 9-3, provides endpoint and policy details for all applications and composites in the domain, the secure status of the endpoints, any configuration overrides and constraints, and if the endpoints have a valid configuration.

Example 9-3 listWebServicesOutput with Valid and Secure Endpoint Configuration

wls:/jrfServer_domain/serverConfig> listWebServices(detail='true')

/jrfServer_domain/jrfServer_admin/jaxws-sut :
        moduleName=jaxws-sut-service, moduleType=web, serviceName={http://namespace/}TestService
        enableTestPage: true
        enableWSDL: true
 
                TestPort        http://host.example.com:9315/jaxws-sut-service/TestService
                enable: true
                enableREST: false
                enableSOAP: true
                maxRequestSize: -1
                loggingLevel: NULL
                management : oracle/log_policy, enabled=true
                security : oracle/wss_username_token_service_policy , enabled=true , effective=false
                Constraint: No Constraint
                        (global) security : oracle/wss_saml_or_username_token_service_policy, enabled=true
                                /policysets/global/all-domains-default-web-service-policies : Domain("*")
                                        reference.priority=1
                Constraint: HTTPHeader('VIRTUAL_HOST_TYPE','external')
                        (global) security : oracle/wss10_message_protection_service_policy, enabled=true
                                /policysets/global/domainExternal : Domain("*")
                Attached policy or policies are valid; endpoint is secure.

For more information about using these WLST commands, see "Viewing the Web Services in a Domain Using WLST".

How the Effective Set of Policies is Calculated

Oracle WSM places a limit on the number of policies that may be attached to a subject based on the categories of the assertions that they contain. In most cases, attaching two or more policies containing the same assertion categories is forbidden. For example, it does not allow two policies containing authentication assertions to be attached to a policy subject, although it does allow one policy containing an authentication assertion and one containing an authorization assertion to be attached to the same subject. If multiple policies containing the same assertion category are attached to a subject, and the assertions conflict, the configuration is considered invalid. For details about the number and combination of policies that can be attached to a subject, see "Validating Policy Subjects"

To support the attachment of policies both directly and externally (globally), the determination of the effective set of policies for a subject takes into account the category of assertions within each policy. Note that policies that are directly attached are attached at the port or component scope. By default, if a subject has a policy attached at the port or component scope (such as a directly attached policy) with an assertion of a given category, then any policies with conflicting assertions of the same category referenced by an external policy set at a higher scope will be excluded from the effective set of policies for the subject, unless the reference.priority configuration override is set, as described below. This process will be repeated at each subject scope. Narrower/lower scopes take precedence over broader/higher scopes. The decreasing order of precedence of policy attachments as determined by scope is as follows:

  • Port (Scope:1)

  • Component (Scope:1)

  • Service (Scope:2)

  • Reference (Scope:2)

  • Composite (Scope: 3)

  • Module (Scope:3

  • Partition (Scope:4)

  • Application (Scope:4)

  • Server (Scope:5)

  • Domain (Scope:6)

For example, a policy attachment at the application scope will be excluded from the effective set of policies for a subject if it contains conflicting assertions of the same category as a policy that was attached at the module scope or attached directly. For additional information about resource scopes, see "Defining the Type and Scope of Resources".

By using the reference.priority configuration override, the administrator can override the default precedence determined by scope and specify a preference over which policy attachment is used. The policy attachment with the highest priority takes precedence, irrespective of its scope.

When using reference.priority overrides, the following rules apply:

  • The policy attachment with the highest priority (highest integer value) takes precedence, regardless of scope.

  • If attachments contain conflicting assertions of the same category and have the same priority specified, the more specific scope takes precedence.

  • If attachments contain conflicting assertions of the same category, priority, and scope, then the configuration is invalid.

When run-time constraints are applied to policy sets, the following rules apply:

  • Each unique constraint creates an independent set of policies. The effective policy calculation is performed only on the set of policies with the same constraint.

  • When no constraint is specified in a policy set (the default), the policy reference in this set is merged with the set of policies from each separate constraint. The effective policy calculation is then performed on each set of policies to determine the effective set of policies for each constraint.

For more information about run-time constraints, see "Specifying Run-time Constraints in Policy Sets".

The effective set of policies calculation takes into account the status of each policy attachment. If a policy, a policy reference in a policy set, or a policy set is disabled, it is removed from the effective set of policies for a subject.

If no reference.priority override is specified, a globally attached policy can be overridden by attaching a policy containing assertions with the same categories at a lower scope (for example at the port or component scope with a direct attachment). As a special case of this, a globally attached policy can be effectively disabled for a specific subject by attaching a policy with the same category of assertions that does not enforce any behavior. For more information about the policies that do not enforce any behavior, see "No Behavior Policies".

The following examples demonstrate the results in effective policy calculations:

  • Direct attachment: oracle/wss_username_token_service_policy

    External attachment: oracle/wss_saml_or_username_token_service_policy @ Domain('*')

    Result: Direct attachment due to lower scope— oracle/wss_username_token_service_policy

  • Direct attachment: oracle/wss_username_token_service_policy

    External attachment: oracle/wss_saml_or_username_token_service_policy @ Domain('*') with reference.priority=1

    Result: External attachment due to higher priority—oracle/wss_saml_or_username_token_service_policy @ Domain('*')

  • External attachment: oracle/wss_username_token_service_policy @ Application('*')

    External attachment: oracle/wss_saml_or_username_token_service_policy @ Domain('*')

    Result: External attachment due to lower scope—oracle/wss_username_token_service_policy @ Application('*')

  • External attachment: oracle/wss_username_token_service_policy @ Application('*')

    External attachment: oracle/wss10_message_protection_service_policy @ Domain('*')

    Result: Both attachments valid due to non-conflicting assertion categories—oracle/wss_username_token_service_policy @ Application('*') and oracle/wss10_message_protection_service_policy @ Domain('*')

  • External attachment: oracle/wss_username_token_service_policy @ Domain('*')

    External attachment: oracle/wss_saml_or_username_token_service_policy @ Domain('*')

    Result: Invalid. Policies with conflicting assertion categories specified at the same scope.

  • Direct attachment: oracle/wss11_saml_token_with_message_protection_service_policy

    External attachment: oracle/wss11_username_token_with_message_protection_service_policy @ Port('TestPort')

    Result: Invalid. Policies with conflicting assertion categories specified at the same scope.

  • Direct attachment: oracle/wss11_saml_token_with_message_protection_service_policy

    External attachment: oracle/wss11_username_token_with_message_protection_service_policy @ Port('TestPort') with reference.priority="true"

    Result: External attachment due to higher priority scope—oracle/wss11_username_token_with_message_protection_service_policy @ Port('TestPort')

Note:

The amount of time it takes for a global policy attachment to take effect is determined by the Oracle WSM policy accessor and policy cache property settings. By default, this delay can be up to a maximum of 11 minutes. To reduce the amount of the delay, you can tune the following cache property settings:

  • Policy Accessor

    cache.refresh.initial, default 600000 milliseconds (10 minutes)

    cache.refresh.repeat, default 600000 milliseconds (10 minutes)

  • Policy Cache

    cache.tolerance, default is 60000 milliseconds (1 minute)

For details about tuning these properties, see "Configuring Platform Policy Properties".