5 Managing Policy Objects

Access Manager provides a Policy Administration API that enables Create, Read, Update, and Delete (CRUD) operations on its policy objects. This chapter describes the API and provides examples for using a RESTful Web service for Access Manager policy administration.

The following sections contain details regarding the Policy Administration API.

5.1 About the Policy Administration API

The Oracle Policy Administration API supports representational state transfer (REST) interfaces for administering Access Manager policy objects as RESTful resources. The API conforms to the Java Specification Request (JSR) 311: JAX-RS 1.1 specifications: Java API for RESTful Web Services 1.1. For more information, see: http://download.oracle.com/otndocs/jcp/jaxrs-1.1-mrel-eval-oth-JSpec/.

This section provides the following topics:

5.1.1 Access Manager Policy Model

The Policy Administration API exposes Access Manager policy model objects (also known as artifacts) to RESTful clients, modeling operations on these objects to HTTP requests containing specific URLs and operations. Operations are subject to Access Manager policy administration rules that enforce policy validation and consistency.

Figure 5-1 shows the policy model and the relationship of the policy objects that can be managed.

Table 5-1 provides details about the policy objects that can be managed using the RESTful interfaces. Each policy object is represented as an HTTP resource that is accessible through an HTTP uniform resource locator (URL).

Table 5-1 Policy Objects

Object Name Description

Application Domain

The top-level construct of the 11g policy model. Each application domain provides a logical container for resources, and the associated authentication and authorization policies that dictate who can access these.

Host Identifier

A host can be known by multiple names. To ensure that Access Manager recognizes the URL for a resource, Access Manager must know the various ways used to refer to that resource's host computer.

Resource

Resources represent a document, or entity, or pieces of content stored on a server and available for access by a large audience. Clients communicate with the server and request the resource (using HTTP methods) that is defined by an existing Resource Type.

Resource Type

A resource type describes the kind of resource to be protected.

Authentication Policy

Authentication policies specify the authentication methodology to be used for authenticating the user. Policies define the way in which the resource access is to be protected.

Authorization Policy

Authorization policies specify the conditions under which a subject or identity has access to a resource.

Token Issuance Policy

A Token Issuance Policy defines the rules under which a token can be issued for a resource (Relying Party Partner) based on the client's identity, with the client either being a Requester Partner or an end user.

Authentication Scheme

A named component that defines the challenge mechanism, level of trust, and the underlying authentication module required to authenticate a user.

Figure 5-2 shows the contents of the Access Manager policies.

You can access the OAM Server RESTful interfaces through client applications such as:

  • Web browsers

  • cURL

  • GNU Wget

5.1.2 Security Model

The Policy Administration REST API is protected by administrative roles. The REST services are protected by the container security that enforces the required roles. The enforcement policy configuration for the API is similar to the policy enforcement for Policy Administration actions performed in the administration console. For example, client invocations are expected to supply credentials in the Authorization Header of the HTTP request, ensuring that the client invocations remain stateless as seen in the following sample request:

Description of appdomainrequest.png follows
Description of the illustration ''appdomainrequest.png''

The following is an example of the response content returned from the sample HTTP request, which contains a list of application domains:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ApplicationDomains>
<ApplicationDomain>
    <name>Demo Application Domain</name>
    <description>Policy objects enabling OAM Agent to protect deployed Demo applications</description>
</ApplicationDomain>
 
<ApplicationDomain>
    <name>Clear Vision Domain</name>
    <description>Policy objects enabling OAM Agents to protect Clear Vision applications</description>
</ApplicationDomain>
</ApplicationDomains>

The authentication provider for user authentication is based on Access Manager application configuration. When the REST service is protected by a Webgate, the Webgate decides about the access request based on the Authentication Scheme associated with the URL. These URLs have Cookieless Basic as the authentication method. The Cookieless Basic scheme should not be changed, instead have it protected with more than one scheme. In such a case, the Webgate treats an access request to these resources as pass-through, preserving the Authorization headers of the request. Access Manager process the request based on the Authorization header provided.

5.1.3 Resource URLs

Resource URLs are structured to include the Access Manager product version, the component exposed by the REST service, and the resources being invoked. The basic structure of a resource URL is as follows:

http(s)://host:port/oam/services/rest/path

where:

  • host is the host where the OAM Server is running.

  • port is the HTTP or HTTPS port.

  • path is the relative path that identifies a particular resource. path is constructed as /version/component/service/ where:

    • version - is the Access Manager product version, such as 11.1.2.0.0

    • component - is the component exposed by the RESTful service, such as ssa or sso

    • service - is the root resource for that given API, such as hostidentifier

    An example of a path value is: /oam/services/rest/11.1.2.0.0/ssa/policyadmin/hostidentifier/host_identifier_name.

The Policy Administration REST Web Application Description Language (WADL) file lists the supported policy resources and methods. The Policy Administration REST WADL document is available at http://adminserver.example.com:adminport/oam/services/rest/11.1.2.0.0/ssa/policyadmin/application.wadl.

Additional parameters are required to process the request query parameters. All resource URLs support the OPTIONS method.

Policy objects can be identified by name or id. If both are provided, the id is used.

Table 5-2 summarizes the resource URLs that are exposed to enable administration of the policy objects shown in Figure 5-1. In the following table:

  • IDENTIFER refers to the name or id of the object the request refers to.

  • APPDOM_IDENTIFER uniquely identifies an existing Application Domain type object by appid or appname.

Table 5-2 Resource URLs

Policy Object URL Artifact Mandatory Parameter

Application Domain

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/appdomain

IDENTIFIER

Host Identifier

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/hostidentifier

IDENTIFIER

Resource Type

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/resourcetype

IDENTIFIER

Resource

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/resource

IDENTIFIER, APPDOM_IDENTIFIER

Authentication Policy

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/authnpolicy

IDENTIFIER, APPDOM_IDENTIFIER

Authorization Policy

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/authzpolicy

IDENTIFIER, APPDOM_IDENTIFIER

Token Issuance Policy

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/tokenpolicy

IDENTIFIER, APPDOM_IDENTIFIER

5.1.4 URL Resources and Supported HTTP Methods

Access Manager policy objects are mapped to URL resources. Each resource is referenced by a global identifier (URI).

Access to URL resources is based on user role. The RESTful service expects user credentials to be present in the Authentication header of the HTTP request in BASIC mode. If the authenticated user has the policy administration role, the requested policy administration action is performed.

5.1.5 Error Handling

A service request can result in various error conditions ranging from invalid service invocation to server side failures. Failures and error code conditions are reported back to the clients as HTTP return codes with an explanatory message.

Table 5-3 contains the mapping between HTTP return codes and message.

Table 5-3 Error Conditions and HTTP Return Codes

Error Condition HTTP Return Code Content

Unable to parse input, or input does not match required entities.

400

Bad request

Service not located

404

Not found

Requested object not found

404

Not found <additional information indicating the not found object)

User not authorized to execute service

401

Unauthorized

Requested method not supported

405

Method not allowed

Client does not accept produced content type

406

Not acceptable

Request parameters semantics incorrect

422

Unprocessable entity <additional information on nature of error>

Client media type unsupported

415

Unsupported media type.

Note: The supported media types are text/xml (or application/xml) and application/json.

Failed dependency

424

Failed dependency <additional information on failed dependency>

Generic server failure

500

Internal server error

5.2 Compatibility

The release version number is embedded as part of the REST service URLs exposed by OAM Server. There is no support for forward compatibility. Clients of newer versions cannot expect to send a request to an older version of OAM Server and receive back newer versions of objects. There is backward compatibility support for older clients.

5.3 Managing Policy Objects

This section provides the following topics:

5.3.1 HTTP Methods

Table 5-4 describes the supported HTTP methods. A successful HTTP method acts upon a representation of the policy object (resource), which is an xml file. A JavaScript Object Notation (JSON) object is returned.

Table 5-4 Methods For Managing Policy Objects

Method Action

GET

Retrieves the policy objects.

POST

Creates the policy object.

PUT

Modify a policy object.

DELETE

Delete a policy object.

5.3.2 Media Types

The supported media types are:

  • application/xml

  • application/json

  • text/xml

5.3.3 Resources Summary

Table 5-5 provides detail about each policy resource, the supported HTTP methods, and the results of each action.

Table 5-5 Access Manager Policy Resources Summary

Resource Method Description

oam/services/rest/11.1.2.0.0/ssa/policyadmin/appdomain

GET

All matching Application Domain resources are returned. If no query parameter is provided, all Application Domain resources are returned. If an ID or NAME query parameter is specified, all matching Application Domain resources are returned.
 

POST

The Application Domain object is created by this method. The request body must contain an Application Domain. An Application Domain object matching the request is created.

All the policy child objects are also created.
 

PUT

An Application Domain object is modified by this method. The request body must contain the Application Domain resource that represents the object.

The Application Domain resource matching the specified ID or NAME query parameter is modified.

If query parameters are not matched, the Application Domain object matching ID or NAME query parameters will be modified. If both ID and NAME are present, the ID value will be used.
 

DELETE

An Application Domain object is deleted by this method. The Application Domain matching NAME or ID query parameter is deleted.

oam/services/rest/11.1.2.0.0/ssa/policyadmin/tokenissuancepolicy

GET

A Token Issuance Policy object is retrieved by this method. The resource that represents the Token Issuance Policy object is returned. This representation contains the matching Token Issuance Policy resource attributes and their values.

Valid query parameters are ID or NAME, and APPDOMAINID or APPDOMAIN. If an APPDOMAINID or APPDOMAIN parameter is not specified, a status code 424 is returned with the appropriate message. If an ID or NAME query parameter is not specified, all Token Issuance Policy resources in the Application Domain are returned.

If the ID or NAME parameter matches, all Token Issuance Policy resources in that Application Domain are returned. In all cases, if both ID and NAME are present, ID will be used.
 

POST

A Token Issuance Policy object is created by this method. The request is performed on the resource that is the parent of the object. The request body must contain a Token Issuance Policy resource that represents the object. A Token Issuance Policy object matching the request is created in the corresponding Application Domain.
 

PUT

A Token Issuance Policy object is modified by this method. The request body must contain the Token Issuance Policy resource that represents the object.

The Token Issuance Policy resource matching the ID or NAME query parameters is modified.

The Token Issuance Policy object should belong to an Application Domain matching the APPDOMAINID or APPDOMAIN query parameter.

If query parameters are not specified, the Token Issuance Policy matching the ID or NAME parameter will be modified.

The Token Issuance Policy should belong to the Application Domain specified in the Application Domain Name attribute. If both ID and NAME are present, ID value will be used.
 

DELETE

A Token Issuance Policy object is deleted by this method. The Token Issuance Policy matching the ID or NAME query parameter, in the Application Domain specified in the APPDOMAINID or APPDOMAIN query parameter, is deleted.

oam/services/rest/11.1.2.0.0/ssa/policyadmin/resource

GET

A Resource object is retrieved by this method. The resources that represents the Resource object is returned. This representation contains the matching Resource resource attributes and their values.

Valid query parameters ID or NAME, and APPDOMAINID or APPDOMAIN. If an APPDOMAINID or APPDOMAIN parameter is not specified, a status code 424 is returned with the appropriate message.

If an ID or NAME query parameter is not specified, all Resource resources in that Application Domain are returned. If the ID or NAME parameter matches, the matching Resource resource in the Application Domain is returned. In all cases, if both ID and NAME are present, ID will be used.
 

POST

A Resource object is created by this method. The request is performed on the resource that is a parent of the object. A Resource object matching the request is created in the corresponding Application Domain.
 

PUT

A Resource object is modified by this method. The request body must contain the Resource resource that represents the object.

The Resource matching ID or NAME query parameters is modified. The Resource should belong to an Application Domain matching the APPDOMAINID or APPDOMAIN query parameter.

If query parameters are not specified, the Resource object matching the ID or NAME specified will be modified.

The Resource should belong to the Application Domain specified in the Application Domain Name attribute.

If both ID and NAME are present, the ID value will be used.
 

DELETE

A Resource object is deleted by this method. The Resource object matching the ID or NAME query parameters, in the Application Domain in the APPDOMAINID or APPDOMAIN query parameters, is deleted.

oam/services/rest/11.1.2.0.0/ssa/policyadmin/authzpolicy

GET

An Authorization Policy object is retrieved by this method. The resource that represents the Authorization Policy object is returned. This representation contains the matching Authorization Policy resource attributes and their values.

Valid query parameters are ID or NAME, and APPDOMAINID or "appdomain". If an appdomainid or APPDOMAIN parameter is not specified, a status code 424 is returned with the appropriate message.

If an ID or NAME parameter is not specified, all Authorization Policy resources in that Application Domain are returned.

If the ID or NAME parameter matches, the matching Authorization Policy resource in the Application Domain is returned. In all cases, if both ID and NAME are present, ID will be used.
 

POST

An Authorization Policy object is created by this method. The request is performed on the resource that is the parent of the object. An Authorization Policy object matching the request is created in the corresponding Application Domain.
 

PUT

An Authorization Policy object is modified by this method. The request body must contain the Authorization Policy resource that represents the object.

The Authorization Policy resources that matching the ID or NAME query parameter is modified.

The Authorization Policy should belong to an Application Domain matching the APPDOMAINID or APPDOMAIN query parameter.

If query parameters are not specified, the Authorization Policy matching the ID or NAME parameter will be modified. The Authorization Policy should belong to the Application Domain specified in the Application Domain Name attribute.

If both ID and NAME are present, ID value will be used.
 

DELETE

An Authorization Policy object is deleted by this method. The Authorization Policy matching the ID or NAME query parameters, in the Application Domain specified in APPDOMAINID or APPDOMAIN query parameters, is deleted.

oam/services/rest/11.1.2.0.0/ssa/policyadmin/hostidentifier

GET

A Host Identifier object is retrieved by this method. The resource that represents the Host Identifier object is returned. This representation contains the matching Host Id en tier resource attributes and their values.

Valid query parameters are ID or NAME. If a query parameter is not specified, all the Host Identifier resources are returned. If the ID or NAME parameter matches, the matching Host Identifier resource is returned.
 

POST

A Host Identifier object is created by this method. The request is performed on the resource that is the parent of the object. A Host Identifier object matching the request is created.
 

PUT

A Host Identifier object is modified by this method. The request body must contain the Host Identifier resource that represents the object.

The Host Identifier resource matching the ID or NAME query parameters is modified. If query parameters are not specified, the Host Identifier matching the ID or NAME parameter will be modified. If both ID and NAME are present, ID value will be used.
 

DELETE

A Host Identifier object is deleted by this method. The Host Identifier matching the ID or NAME query parameter is deleted.

oam/services/rest/11.1.2.0.0/ssa/policyadmin/resourcetype

GET

A Resource Type object is retrieved by this method. The resource that represents the Resource Types object is returned. This representation contains the matching Resource Type resource attributes and their values.

Valid query parameters ID or NAME. If a query parameter is not provided, all Resource Type resources are returned. If the query parameter id or name matches, the matching Resource Type is returned.
 

POST

A Resource Type object is created by this method. The request body is performed on the parent of the object. A Resource Type object matching this request is created.
 

PUT

A Resource Type object is modified by this REST method. The request body must contain the Resource Type resource that represents the object.

The Resource Type resource matching ID or NAME query parameter is modified. If query parameters are not specified, the Resource Type matching the ID or NAME parameter will be modified. If both ID and NAME are present, ID value will be used.
 

DELETE

A Resource Type object is deleted by this method. The Resource Type matching the NAME or ID query parameter is deleted.

oam/services/rest/11.1.2.0.0/ssa/policyadmin/authnscheme

GET

An Authentication Scheme object is retrieved by this method. The resource that represents the Authentication Schemes object is returned. This representation contains the matching Authentication Scheme resource attributes and their values.

Valid query parameters are ID or NAME. If a query parameter is not specified, all Authentication Scheme resources are returned. If the query parameter ID or NAME matches, the matching Authentication Scheme is returned.
 

POST

An Authentication Scheme object is created by this method. The request is performed on the resource that is the parent of the object. An Authentication Scheme object matching the request is created.
 

PUT

An Authentication Scheme object is modified by this method. The request body must contain the Authentication Scheme resource that represents the object.

The Authentication Scheme resource matching the ID or NAME query parameter is modified. If query parameters are not specified, the Authentication Scheme matching ID or NAME parameter will be modified. If both ID and NAME are present, ID value will be used.
 

DELETE

An Authentication Scheme object is deleted by this method. The Authentication Scheme matching the NAME or ID query parameter is deleted.

/oam/services/rest/11.1.2.0.0/ssa/policyadmin/application.wadl

GET

Web Application Definition Document is generated. It describes the REST services provided. The document contains a stylesheet reference that renders HTML content.

5.4 Client Tooling

Two XML schemas are available for generating client side POJOs, which represent the RESTful service resources:

  • For the policyadmin service, the schema is oam-policyadmin-11.1.2.0.0.xsd.

  • For the token service, the schema is oam-token-11.1.2.0.0.xsd.

To generate the client side object, run the JAXB command xjc (part of the JDK) as follows:

xjc  [-p package-name] oam-policyadmin-11.1.2.0.0.xsd

This command generates the Java POJO objects for the RESTful resources, which can be used in the client side Java code. These objects can be converted back to XML using JAXB and can then be sent to the REST server over HTTP.

For more information about JAXB, see http://jaxb.java.net/. For more information about building clients for Jersey-based REST server, see http://jersey.java.net/.

Retrieve Application Domains cURL Command

$ curl -u USER:PASSWORD http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/appdomain

The following is sample output from this cURL command.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ApplicationDomains>
<ApplicationDomain>
    <id>759463e3-2b63-4e38-893c-00d5da479719</id>
    <name>IAM Suite</name>
    <description>Policy objects enabling OAM Agent to protect deployed IAM Suite applications</description>
</ApplicationDomain>
 
<ApplicationDomain>
    <id>69f6be9b-f000-48db-9b6d-df4724cc0bd9</id>
    <name>Fusion Apps Integration</name>
    <description>Policy objects enabling integration with Oracle Fusion Applications</description>
</ApplicationDomain>

Create a New Application Domain cURL Command

curl -u weblogic:welcome1 -H "Content-Type: application/xml" --request POST --data "@/tmp/cr.appdomain.xml" http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/appdomain

The following is a sample input file for this cURL command.

<ApplicationDomain>
    <name>Appdomain1</name>
    <description>test application domain</description>
</ApplicationDomain>

The following is sample output from this cURL command.

http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/appdomain?id=fa60e312-fe65-4aa8-aace-1735a39c4058

Retrieve All Authentication Schemes cURL Command

curl -u USER:PASSWORD http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/authnscheme

The following is sample output from this cURL command.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AuthenticationSchemes>
  <AuthenticationScheme>
      <id>aa84b589-7f16-4b3a-942c-ba51b3ab6de5</id>
      <name>KerberosScheme</name>
      <description>Kerberos Scheme</description>
      <authnModuleName>Kerberos</authnModuleName>
      <authnSchemeLevel>2</authnSchemeLevel>
      <challengeMechanism>WNA</challengeMechanism>
      <ChallengeParameters>
          <challengeParameter>
              <key>spnegotoken</key>
              <value>string</value>
          </challengeParameter>
          <challengeParameter>
              <key>challenge_url</key>
              <value>/oam/CredCollectServlet/WNA</value>
          </challengeParameter>
      </ChallengeParameters>
      <challengeRedirectURL>/oam/server/</challengeRedirectURL>
  </AuthenticationScheme>
</AuthenticationSchemes>

Create an Authentication Scheme cURL Command

curl -u weblogic:welcome1 -H "Content-Type: application/xml" --request POST --data "@/tmp/cr.authnscheme.xml" http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/authnscheme

The following is a sample input file.

<AuthenticationScheme>
    <name>TestAuthnScheme</name>
    <description>test authn scheme</description>
    <authnModuleName>TestModule1</authnModuleName>
    <authnSchemeLevel>2</authnSchemeLevel>
    <challengeMechanism>WNA</challengeMechanism>
    <ChallengeParameters>
        <challengeParameter>
            <key>spnegotoken</key>
            <value>string</value>
        </challengeParameter>
        <challengeParameter>
            <key>challenge_url</key>
            <value>/oam/CredCollectServlet/WNA</value>
        </challengeParameter>
    </ChallengeParameters>
    <challengeRedirectURL>/oam/server/</challengeRedirectURL>
</AuthenticationScheme>
~

The following is sample output from this cURL command.

http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/authnscheme?id=acb1fa95-f780-4091-be88-2e96cf5bbd49

Retrieve a Specific Authentication Scheme cURL Command

curl -u USER:PASSWORD http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/authnscheme?name=KerberosScheme

The following is sample output from this cURL command.

<AuthenticationScheme>
      <id>aa84b589-7f16-4b3a-942c-ba51b3ab6de5</id>
      <name>KerberosScheme</name>
      <description>Kerberos Scheme</description>
      <authnModuleName>Kerberos</authnModuleName>
      <authnSchemeLevel>2</authnSchemeLevel>
      <challengeMechanism>WNA</challengeMechanism>
      <ChallengeParameters>
          <challengeParameter>
              <key>spnegotoken</key>
              <value>string</value>
          </challengeParameter>
          <challengeParameter>
              <key>challenge_url</key>
              <value>/oam/CredCollectServlet/WNA</value>
          </challengeParameter>
      </ChallengeParameters>
      <challengeRedirectURL>/oam/server/</challengeRedirectURL>
  </AuthenticationScheme>

Retrieve All Resources in an Application Domain cURL Command

curl -u USER:PASSWORD http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/resource?appdomain="IAM Suite"

Create a Resource in an Application Domain cURL Command

curl -u weblogic:welcome1 -H "Content-Type: application/xml" --request POST --data "@/tmp/cr.resource.xml" http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/resource?appdomain="AppDomain1"

Retrieve All Policies in an Application Domain cURL Command

curl -u USER:PASSWORD http://<SERVER>:<PORT>/oam/services/rest/11.1.2.0.0/ssa/policyadmin/authnpolicy?appdomain="IAM Suite"