Using the Authentication Policy

Learn how to create and configure an Authentication policy, which dictates the identity and domain/realm to use when authenticating the message sender.

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

Table of Contents

Introduction

The Authentication policy allows you to protect your services by applying authentication to messages and by making sure that the messages come from trusted domains.

In order to protect services from unauthorized parties, the initiators of a web service message exchange must be identified. WS-Security specifies mechanisms for representing identities in a message exchange; however, it only addresses how the messages themselves can be tied to an identity.

It's important to also make sure that the sending identity is:

  • Authentic
  • Known to the service
  • Authorized to invoke the service

For services that require the caller to be known, authentication of the identity associated with request messages must be performed. Identities are tied to trust domains or security realms. A service might support identities in multiple security realms.

Identification of the requirement for authentication and which security realm, or domain, must be used for authentication is configured through an authentication policy.

Specification:

Creating an Authentication 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.

At this point, you've created the policy, but it doesn't do anything. The next step is to configure the policy details. See Configuring an Authentication Policy below.

Configuring an Authentication Policy

Once you've created the policy, you can configure the policy details that determine how the policy works. Then you can activate the policy so that it can be used.

To configure an Authentication policy in Policy Manager

  1. In the Organization Tree, find the level where the policy was defined. Click to select.
  2. In the center pane, in the Authentication Policy section, click Modify. The Modify Authentication Policy overlay is displayed, as shown below.

    Modify Authentication Policy

  3. Specify values for the subject category and domains that the policy will apply to, and the audit options. For details on field values, see Authentication Policy Options below.
  4. Click Apply.

Now that the policy is defined, you can activate it and start using it. On the right, under Actions, choose Activate Policy.

Authentication Policy Options

The Authentication policy includes the options listed below.

Subject Category
Indicates the identity that will be authenticated. Options:
  • Consumer (the default): Authenticates the consumer identity sent with a request message.
  • End-User: Audits the end-user identity sent with a request message.
  • User Defined: If you choose User Defined, specify a custom category name; for example, a platform identity.
Domains (Realms)
Specify one or more realms to which authentication will be applied. Valid realms are displayed on the left. Highlight a realm and then click >> to choose to authenticate messages using that realm. You can choose one or more. You can also arrange the realms you've selected in order of priority.
Audit options
Choose from the available options to determine the audit data that the policy will capture:
  • Generate Audit Data: Enables the audit feature. By default, this captures all message data, whether success or failure, for all message exchanges.
  • On Error Only: If you choose to generate audit data, you can specify that audit data is captured only when an error occurs on a message exchange.

Policy Assertion

Syntax:

The syntax of the authentication policy assertion is as follows:

01) <ganp:Authentication SubjectCategory="xs:anyURI" ...>
02)   <ganp:Realm>xs:anyURI</ganp:Realm> +
03)   ...
04) </ganp:Authentication>
ganp:Authentication
Authentication policy assertion element.
ganp:Authentication/@SubjectCategory
This required attribute identifies the specific identity associated with the message to authenticate by category. The SubjectCategory is specified as a URI and must correspond to a SubjectCategory specified in the security policy governing the same message.
ganp:Authentication/ganp:Realm
URI representing the trust realm, or domain, in which the authentication is performed.
ganp:Authentication /@{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.
ganp:Authentication /{any}
This is an extensibility mechanism to allow additional elements to be specified.

Syntax example:

An example of an authentication policy is illustrated below:

01) <wsp:Policy Visibility="private" xmlns:wsp="...">
02)   <ganp:Authentication SubjectCategory="urn:ganp:security:subject-category:consumer">
03)     <ganp:Realm>example.com</ganp:Realm>
04)     <ganp:Realm>bankingfederation.org</ganp:Realm>
05)   </ganp:Authentication>
06) </wsp:Policy>

On line 02, the SubjectCategory attribute indicates that this policy is for authenticating consumers. Lines 03 and 04 identify two realms that the consumer identities could be a part of, example.com and bankingfederation.org. It is assumed that the container has the ability to authenticate users in those realms, either directly or indirectly.

Policy Scope

The authentication 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 authentication 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 authentication policy assertion MAY be attached to the following physical WSDL policy attachment points:

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

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

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

01) <wsdl:definitions name="StockQuote" targetNamespace="..." xmlns:wsdl="..." xmlns:wsoap12="..." xmlns:wsp="..." xmlns:wsu="..." xmlns:ganp="..." >
02)   <wsp:Policy wsu:Id="Auth1" visibility="private">
03)     <ganp:Authentication>
04)       <!-- Details omitted for readability -->
05)     </ganp:Authentication>
06)   </wsp:Policy>
07)   <wsp:Policy wsu:Id="Auth2" visibility="private">
08)     <ganp:Authentication>
09)       <!-- Details omitted for readability -->
10)     </ganp:Authentication>
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="#Auth1" wsdl:required="true" />
18)     </wsdl:operation>
19)     <wsdl:operation name="GetSymbol" />
20)       <wsdl:input message="..." />
21)       <wsdl:output message="..." />
22)       <wsp:PolicyReference URI="#Auth2" wsdl:required="true" />
23)     </wsdl:operation>
24)   </wsdl:portType>
25) </wsdl:definitions>

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

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 policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.

Authentication policy use cases

The Authentication policy is configured and uses as part of the following use case: