Using the Authorization Policy

Learn how to use the Authorization policy to authorize the end-user Subject of an API call, including specifying the identity system (domain or realm) that will be the authorization agent.

For information about using policies in the context of the Community Manager developer portal, see Business Policies.

Table of Contents

Introduction

A typical governance requirement is to provide authorization of the use of services. The authorization rules are defined using a Governance Application. The authorization rules are enforced by two collaborating parties, a Policy Decision Point (PDP) and a Policy Enforcement Point (PEP). The container acts as a PEP. The container might also act as a PDP, but typically it simply integrates with a PDP. It is also possible that multiple PDPs are leveraged within an SOA and must be integrated with the container.

Information relating to authorization, including identification of the requirement for authorization and details about the PDP that must be used for authorization, is configured through an authorization policy.

Specification:

Creating an Authorization policy

The first step in creating a policy is to define the basic policy information.

To add an operational policy

  1. Go to Workbench > Browse > Organization, and select Policies > Operational Policies. The Policies Summary is displayed.
  2. Click Add Policy.
  3. Choose the policy type and click Next.
  4. Specify a name (required) and description (optional) and click Finish. At the Completion Summary, click Close. The Add Policy Wizard creates a draft policy instance that you can then configure on the Policy Details page.

For more information, see Add Policy.

Configuring the Authorization Policy

To configure your Authorization policy, follow the steps below.

To configure the Authorization policy

  1. Create the policy as covered above.
  2. At the Policies Summary page, in the Authorization policy section, click Modify. The Modify Authorization Policy page appears, as shown below.

    Modify Authorization Policy page

  3. Specify values. For information about the fields, refer to Configuring Authorization Policy Options below.
  4. When done, click Finish.

Configuring Authorization Policy Options

Once you've created the policy, you can configure the policy options. The sections below provide more information on the options available.

Subject Category
Options:
  • Consumer: The consumer of the service; the client application. This is the default and most common value.
  • End-User: The end-user of the client application.
  • User-Defined: You can define a specific subject category that will be used for identification purposes. If you choose this option, specify the value that will be used. Make sure you spell it exactly correctly, including capitalization.
Domain (Realm)
Allows you to define the trust realm or domain in which authorization is performed. Options:
  • Local Domain: Allows you to specify that authorization is done at the local domain level.

    If you choose Local Domain, the End-User authorization is done locally using the Authorization Rules configured for the service/API. These Authorization Rules are configured using the Policy Manager Console.

  • External Domain: Allows you to use an integrated identity system and configure authorization for an external domain.

    Choosing this option allows an Identity System to be used as the Authorization Agent. It must already be configured on the platform, and is then available in the drop-down list. There are two Identity System types that support authorization: SiteMinder and Claims. In the case of SiteMinder, the authorization rules are specified using the SiteMinder Policy Server admin tools.

    Select from the drop-down list of valid options and specify Resource, Action, or both. Resource represents the established authorization method of the external domain; for example, it could be a user, administrator, local group, domain, or local group. Each resource is assigned privileges that provide an authorization result; for example, prompt for authorization, authorization not required. Action represents the level of authorization assigned to a user; for example, admin authorization, root authorization, no authorization.

Generate Audit Data
Captures all message data, whether success or failure, for all message exchanges.
If you choose to generate audit data, you can check On Error Only to specify that audit data is captured only when an error occurs on a message exchange.

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Attaching a policy

To use the Authorization policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.

Authorization Policy Assertion

The syntax of the authorization policy assertion is as follows:

01)  <gazp:Authorization SubjectCategory="xs:anyURI" ...>
02)    <gazp:Realm>xs:anyURI</gazp:Realm>
03)    (
04)      <xacml:Resource>xacml:ResourceType</xacml:Resource>
05)      <xacml:Action>xacml:ActionType</xacml:Action>
06)    ) ?
07)    ...
08)  </gazp:Authorization>
gazp:Authorization
Authorization policy assertion element.
gazp:Authorization/@SubjectCategory
This required attribute identifies the specific identity associated with the message to authorize by the category of the authenticated subject. The SubjectCategory is specified as a URI and must correspond to a SubjectCategory specified in the security policy governing the same message.
gazp:Authorization/gazp:Realm
URI representing the trust realm, or domain, in which the authorization is performed.
gazp:Authorization/xacml:Resource
The optional element identifies the resource to authorize access to as defined by the XACML specification. If the element is not included, it is assumed that the PDP can make its authorization decisions using only the context of the message received.
gazp:Authorization/xacml:Action
The optional element identifies the action to authorize access to as defined by the XACML specification. The element is required if the xacml:Resource element is included.
gazp:Authorization /@{any}
Additional attributes MAY be specified but MUST NOT contradict the semantics of the [owner element]; if an attribute is not recognized, it SHOULD be ignored.
gazp:Authorization /{any}
This is an extensibility mechanism to allow additional elements to be specified.

An example of an authorization policy is illustrated below:

01)  <wsp:Policy Visibility="private" xmlns:wsp="...">
02)    <gazp:Authorization SubjectCategory="urn:gazp:security:subject-category:consumer" xmlns:soa="...">
03)      <gazp:Realm>example.com</gazp:Realm>
04)      <xacml:Resource>
05)        <xacml:Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:resource:resource-id" DataType="http://www.w3.org/2001/XMLSchema#anyURI">
06)          <xacml:AttributeValue>
07)            http://example.com/consumerBanking
08)          </xacml:AttributeValue>
09)        </xacml:Attribute>
10)      </xacml:Resource>
11)      <xacml:Action>
12)        <xacml:Attribute AttributeId="urn:oasis:names:tc:xacml:2.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#string">
13)          <xacml:AttributeValue>
14)            getQuote
15)          </xacml:AttributeValue>
16)        </xacml:Attribute>
17)      </xacml:Action>
18)    </gazp:Authorization>
19)  </wsp:Policy>

In the above:

  • On line 02 the SubjectCategory attribute indicates this policy is for authenticating consumers.
  • Line 03 identifies the example.com realm that will make the authorization decision.
  • Lines 04–10 identify the protected resource in the example.com realm that is being requested access to.
  • Lines 11–17 identify the action on that resource that is being performed.

Authorization Policy Scope

The authorization policy assertion can have the following Policy Subjects as defined in the WS-PolicyAttachment specification:

  • Service Policy Subject
  • Endpoint Policy Subject
  • Operation Policy Subject

The WS-PolicyAttachment specification defines a set of WSDL/1.1 policy attachment points for each of the above Policy Subjects. Since an authorization policy assertion has no dependency on any WSDL binding, it SHOULD be attached to the following abstract WSDL policy attachment points:

  • wsdl:service
  • wsdl:port
  • wsdl:portType
  • wsdl:portType/wsdl:operation

An authorization policy assertion MAY be attached to the following physical WSDL policy attachment points:

  • wsdl:binding
  • wsdl:binding/wsd:operation

An authorization policy does not dictate any behavior required by a consumer in order to complete message exchanges. Therefore it is RECOMMENDED that authorization policies be classified as private by including the gazp:Visibility attribute in the enclosing wsp:Policy element with a value of private.

The following is an example of an authorization policy attached to WSDL components.

01) <wsdl:definitions name="StockQuote" targetNamespace="..." xmlns:wsdl="..." xmlns:wsoap12="..." xmlns:wsp="..." xmlns:wsu="..." xmlns:gazp="..." >
02)   <wsp:Policy wsu:Id="Authz1" visibility="private">
03)     <gazp:Authorization>
04)       <!-- Details omitted for readability -->
05)     </gazp:Authorization>
06)   </wsp:Policy>
07)   <wsp:Policy wsu:Id="Authz2" visibility="private">
08)     <gazp:Authorization>
09)       <!-- Details omitted for readability -->
10)     </gazp:Authorization>
11)   </wsp:Policy>
12)   <wsdl:import namespace="..." location="..." />
13)   <wsdl:portType name="StockQuote">
14)     <wsdl:operation name="GetQuote" />
15)       <wsdl:input message="..." />
16)       <wsdl:output message="..." />
17)       <wsp:PolicyReference URI="#Authz1" wsdl:required="true" />
18)     </wsdl:operation>
19)     <wsdl:operation name="GetSymbol" />
20)       <wsdl:input message="..." />
21)       <wsdl:output message="..." />
22)       <wsp:PolicyReference URI="#Authz2" wsdl:required="true" />
23)     </wsdl:operation>
24)   </wsdl:portType>
25) </wsdl:definitions>

In the above:

  • Lines 02–11 are two authentication policies, Authz1 and Authz2.
  • Authz1 is associated with the GetQuote operation on line 17.
  • Authz2 is associated with the GetSymbol operation on line 22.