Using Web Services for Object and Row-Level Data Authorization

This chapter discusses how to:

• Develop request messages for the security authorization service.

• Work with response messages for the security authorization service.

• Develop the security authorization service application class.

• Configure content references and components to use the security authorization service.

• Test and debug the security authorization service.

Understanding Using Web Services for Object and Row-Level Data Authorization

PeopleSoft provides a security authorization service that you can use to authorize access to PeopleSoft objects and row-level data on local and remote PeopleSoft nodes.

Note. The terms security authorization service and authorization service are used interchangeably in this chapter.

Object Authorization

You can use the security authorization service to authorize basic security access to content references, components and, pagelets. You can also use the service to get the authorize for users to run PeopleSoft queries and iScripts.

Row-Level Data Authorization

The security authorization service enables you to authorize row-level data access to data on local and remote PeopleSoft notes.

For example, in the related content framework, you can create related services out of components residing on a remote node and assigned them as related actions to a component on the local node. You can use the security authorization service to determine if a user can access the services using the related actions on the local node.

Basic security to a content reference or component must be cleared before the system tests for and authorizes row-level data access.

Understanding Developing and Invoking the Security Authorization Service

This section provides an overview of developing and invoking the security authorization service.

Developing and Invoking the Security Authorization Service for Object Authorization

The section provides the high-level steps for developing and invoking authorization services to authorize user access to content references, components, pagelets, PeopleSoft queries, and iScripts.

Object Authorization on Local Nodes

For basic data authorization on a local node:

• Develop a SOAP request message.

• Invoke the service by performing a direct application class method invocation with the request message

Object Authorization on Remote Nodes

For object authorization on a remote node:

• Develop a SOAP request message.

• Invoke the service by sending a SyncRequest to the remote node.

Developing and Invoking the Security Authorization Service for Row-Level Data Authorization

This section provides the high-level steps for developing and invoking authorization services to authorize row-level data access to components and content references.

Row-Level Data Authorization on Local Nodes

For row-level data authorization on a local node:

• Develop a SOAP request message.

• Develop an application class.

• Use the Authorization page to configure the component or content reference for using the authorization service application class.

• Invoke the service operation by calling the authorization service application class method OnAuthRequest()

Row-Level Data Authorization on Remote Nodes

For row-level data authorization on a remote node:

• Develop a SOAP request message.

• Develop an application class.

• Use the Authorization page to configure the component or content reference for using the authorization service application class.

• Invoke the service operation by performing a SyncRequest to the remote node.

Understanding Security Authorization Service Metadata

The following table describes the delivered authorization service metadata.

Note. Developers must create request, response, and any fault messages to use with this service.

Understanding Code Examples in this Chapter

This chapter contains pseudocode examples to help illustrate using services to authorize object and row-level data access. The code examples are for illustrative purposes only and are not intended to be used in a production environment.

The code examples for authorization service request messages feature all required elements. They may also feature some, but not necessarily all, optional elements. Please refer to the table in the Authorization Service Request Message Elements section of this chapter for a list of all required and optional elements for authorization service request messages.

See Request Message Elements for the Security Authorization Service.

Prerequisites for Developing Services for Object and Row-Level Authorization

To develop services for object and row-level authorization you should have a general understanding of the PeopleSoft services-oriented architecture and PeopleSoft Integration Broker.

In addition, the following items must be set to use the authorization service:

• Target and schema namespaces.

  See Configuring PeopleSoft Integration Broker for Handling Services.

• Service operation permissions.

  See Setting Permissions to Service Operations.

• Authentication domain.

  See Configuring General Portal Properties.

• WS-Security.

  See Implementing Web Services Security.

Developing Request Messages for the Security Authorization Service

This section discusses:

• Request message elements for the security authorization service.

• Request messages for authorizing access to content references.

• Request messages for authorizing access to components.

• Request messages for authorizing access to PeopleSoft queries.

• Request messages for authorizing access to PeopleSoft pagelets.

• Request messages for authorizing access to iScripts.

Understanding Developing Request Messages for the Security Authorization Service

An authorization service request message contains a SOAP header followed by a number of authorization request elements.

Inside the message envelope is the PARAMARRAY element. The PARAMARRAY element can contain none to many PARAMS elements. Each PARAMS element corresponds to a separate authorization request. You can bundle multiple requests into a single request.

The following pseudocode shows an example of a request message for the authorization service containing two authorization requests. Each request is contained in a PARAMS element:

<!-- Begin SOAP header -->
<?xml version="1.0"?>
<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://
schemas.xmlsoap.org/ws/2003/03/addressing/" xmlns:xsd="http://www.w3.org/2001/
XMLSchema/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance/">
  <soapenv:Header xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <wsse:Security soap:mustUnderstand="1" xmlns:soap="http://schemas.xmlsoap.org/
     wsdl/soap/" xmlns:wsse="http://docs.oasis- 
      open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>PTDMO</wsse:Username>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <FindAccess xmlns="http://xmlns.oracle.com/Enterprise/Tools/schemas/
     PTCSSecurityReq.v1">

<!-- End SOAP header -->
<!-- Begin message envelope -->

     <PARAMARRAY>
        <PARAMS>
           <SERVICEID>1</ SERVICEID >
           <SERVICE_TYPE>UPGE</SERVICE_TYPE>
           <NODE>PT_LOCAL</NODE>
           <MENU>APPLICATION_ENGINE</MENU>
           <COMPONENT>AE_TOOLS</COMPONENT>
           <MARKET>GBL</MARKET>
           <COMP_ITEM_NAME>SCPERSONALDICT</COMP_ITEM_NAME>
           <KEYVAL>ACTION=U</KEYVAL
           <KEYVAL>SET_ID=S3</KEYVAL>
           <KEYVAL>CUSTOMERID=CATHYPACIFIC</KEYVAL>
        </PARAMS>

        <PARAMS>
           <SERVICEID>2</ SERVICEID >
           <SERVICE_TYPE>CREF</SERVICE_TYPE>
           <PORTAL>EMPLOYEE</PORTAL>
           <NODE>PT_LOCAL</NODE>
           <CREFID>SCPERSONALDICT</CREFID>
           <KEYVAL>NAME=RAJASIMHAN</KEYVAL>
           <KEYVAL>NAME=ARTHI</KEYVAL>
           <KEYVAL>SET_ID=S3</KEYVAL>
        </PARAMS>
     </PARAMARRAY>

     <!-- End message envelope -->

    </FindAccess>
  </soapenv:Body>
</soapenv:Envelope>

Important! If the service is invoked on a remote node, it will run on the context of the user ID provided in the <wsse:Username> element defined in the request message header. If the service is invoked on a local node by creating an application class object, the system ignores the <wsse:Username> element value and it executes the code in the context of the user.

Request Message Elements for the Security Authorization Service

The following table describes elements and their usage for request messages used in the security authorization service:

<KEYVAL>AE_PRODUCT=S3</KEYVAL>
<KEYVAL>CUSTOMERID=CATHYPACIFIC</KEYVAL>

<KEYVAL>ACTION=U<KEYVAL>

Request Messages for Authorizing Access to Content References

The following pseudocode shows an example of the PARAMS section of a request message for authorizing access to a content reference:

<PARAMARRAY>
   <PARAMS>
      <SERVICEID>1</SERVICEID>
      <SERVICE_TYPE>CREF</SERVICE_TYPE>
      <NODE>PT_LOCAL</NODE>
      <CREFID>SCPERSONALDICT</CREFID>
       <PORTAL>EMPLOYEE</PORTAL>
   </PARAMS>
</PARAMARRAY>

If no value is supplied for the PORTAL element the service uses the value of the default local portal assigned to the node.

See Also

Understanding Code Examples in this Chapter

Request Messages for Authorizing Access to Components

This section discusses request messages for authorizing access to components and provides code examples of request messages.

IsMenuItemAuthorized

If menu, component and component item name are available, the IsMenuItemAuthorized function call can be used to get authorization. Note that barname and itemname are obtained using menu, market and component name.

If component item name is not available, then the IsMenuItemAuthorized function is invoked for each component item name (page) in the component. The user is provided access even if he or she has access to one of the pages in the component.

Action mode (Update, Update/Display) and other service parameters that need to be passed on to the authorization service application class can be passed to the IsMenuItemAuthorized function through the KEYVAL element with the keyname ACTION . See the Authorization Service Request Message Elements chart presented earlier in this section for additional information about using the KEYVAL element and the key name ACTION.

Component Authorization Request Messages: Component Name and Action Mode are Available

The following pseudocode shows an example of the PARAMS section of a request message for authorizing access to a component when the component item name and action mode are available:

<PARAMARRAY>
   <PARAMS>
      <SERVICEID>1</SERVICEID>
      <SERVICE_TYPE>UPGE</SERVICE_TYPE>
      <MENU>APPLICATION_ENGINE</MENU>    
      <COMPONENT>AE_TOOLS</COMPONENT>
      <COMP_ITEM_NAME>COMP_ITEM_NAME</COMP_ITEM_NAME>
      <MARKET>GBL</MARKET>
      <KEYVAL>ACTION=U</KEYVAL>
      <NODE>PT_LOCAL</NODE>
   </PARAMS>
</PARAMARRAY>

Component Authorization Request Messages: Action Type is ot Available

The following pseudocode shows an example of the PARAMS section of a request message for authorizing access to a component when the action type is not available. In such cases the action type is determined by the code:

<PARAMARRAY>
   <PARAMS>
      <SERVICEID>1</SERVICEID>
      <SERVICE_TYPE>UPGE</SERVICE_TYPE>
      <MENU>APPLICATION_ENGINE</MENU>    
      <COMPONENT>AE_TOOLS</COMPONENT>
      <COMP_ITEM_NAME> COMP_ITEM_NAME</COMP_ITEM_NAME>
      <MARKET>GBL</MARKET>
   </PARAMS>
</PARAMARRAY>

Component Authorization Request Messages: Component Item Name is Not Available

If a component item name is not present then it is derived as follows: For each of the pages in the component the IsMenuItemAuthorized function is invoked by passing the component item name of each page; if the user has access to the component for at least one of the pages in the component the authorization service will return true.

The following pseudocode shows an example of the PARAMS section of a request message for authorizing access to a component when the component item name is not available, but values for PORTAL and MARKET elements are available:

<PARAMARRAY>
   <PARAMS>
      <SERVICEID>1</SERVICEID>
      <SERVICE_TYPE>UPGE</SERVICE_TYPE>
      <NODE>PT_LOCAL</NODE>
      <MENU>APPLICATION_ENGINE</MENU>
      <COMPONENT>AE_TOOLS</COMPONENT>
      <MARKET>GBL</MARKET>
      <PORTAL>EMPLOYEE</PORTAL>used ]
   </PARAMS>
</PARAMARRAY>

The following pseudocode shows an example of the PARAMS section of a request message for authorizing access to a component when no values for COMP_ITEM_NAME, PORTAL or MARKET elements are specified. The value for PORTAL is defaulted to the portal of the default provider node; the value for MARKET is defaulted to GBL.

<PARAMARRAY>
   <PARAMS>
      <SERVICE_TYPE>UPGE</SERVICE_TYPE>
      <NODE>PT_LOCAL</NODE>
      <MENU>APPLICATION_ENGINE</MENU>
      <COMPONENT>AE_TOOLS</COMPONENT>
   </PARAMS>
</PARAMARRAY>

Request Messages for Authorizing Access To PeopleSoft Queries

The following pseudocode shows an example of the PARAMS section of a request message for authorizing access to a PeopleSoft query:

<PARAMARRAY>
   <PARAMS>
      <SERVICE_TYPE>UQRY</SERVICE_TYPE>
      <QUERY>MESSAGE_FOR_MESSAGESET</QUERY>
   </PARAMS>
</PARAMARRAY>

The authorization service uses the Query API to get the query authorization for the user.

Request Messages for Authorizing Access to PeopleSoft Pagelets

There are three types of PeopleSoft pagelets: .

• Pagelet wizard pagelets.

• Component-based pagelets.

• iScript-based pagelets.

This section provides code examples of the PARAMS section requests messages for authorizing access to these types of PeopleSoft pagelets.

Request Messages for Authorizing Access to Pagelet Wizard Pagelets

To authorize a user for a pagelet wizard pagelet, you must pass the pagelet ID. The following pseudocode example shows passing the pagelet ID:

<PARAMARRAY>
   <PARAMS>
      <SERVICE_TYPE>POP</SERVICE_TYPE>  OR  <SERVICE_TYPE>PEP</SERVICE_TYPE>  
      <PAGELETID>PAGELET_ID</PAGELETID>
   </PARAMS>
</PARAMARRAY>

Request Message for Authorizing Access to Component and iScript Pagelets

To authorize a user to access a component or iScript-based pagelet used the service type CREF instead of POP or PEP and pass the CREFID like any other CREF service type request:

<PARAMARRAY>
   <PARAMS>
      <SERVICEID>1</SERVICEID>
      <SERVICE_TYPE>CREF</SERVICE_TYPE>
      <CREFID>PAGELET_CREF_ID</CREFID>
   </PARAMS>
<PARAMARRAY>

The authorization service queries PeopleTools security data to get the permission lists that can access this iScript. It then checks if the user has access to the permission list.

Request Messages for Authorizing Access to iScripts

The following pseudocode shows an example of the PARAMS section of a request message to authorize access to a PeopleSoft iScript:

<PARAMARRAY>
   <PARAMS>
      <SERVICE_TYPE>USCR</SERVICE_TYPE>
      <NODE>PT_LOCAL</NODE>
      <RECORD>WEBLIB_RPT</RECORD>
      <FIELD>ISCRIPT1</FIELD>
      <FUNCTION>IScript_Test</FUNCTION>
    </PARAMS>
</PARAMARRAY>

The authorization service uses the Pagelet Wizard security data to get pagelet authorization for a user..

See Also

Understanding Code Examples in this Chapter

Working with Response Messages for the Security Authorization Service

This section discusses how to:

• Read authorization status in response messages.

• Evaluate response messages that contain multiple responses.

• Read validation and error information in response messages.

Reading Authorization Status in Response Messages

An authorization service response message contains the element ACCESS which can contain the following values:

• T. User can access the content reference, menu, pagelet, query, iScript or row-level data.

• F. User is denied access to the content reference, menu, pagelet, query, iScript or row-level data.

Evaluating Response Messages that Contain Multiple Responses

If the request message has three (3) PARAMS elements that correspond to three (3) requests, the response message also contains three (3) PARAMS elements. Each PARAMS element in the response message contains an ACCESS element to convey the authorization status for each corresponding request.

In cases where there are multiple sub requests in a single request, the sub responses do not appear in the same order in the response message as the sub requests in the request message. Use the SERVICEID element value to map the sub responses to the sub requests.

The following examples show how the SERVICEID element maps sub-requests to sub-responses:

The following example shows requests in the order SVC_1, SVC_2, and SVC_3:

<PARAMARRAY>

   <PARAMS>
     <SERVICEID>SVC_1</SERVICEID>
   </PARAMS>

   <PARAMS>
     <SERVICEID>SVC_2</SERVICEID>
   </PARAMS>

   <PARAMS>
     <SERVICEID>SVC_3</SERVICEID>
   </PARAMS>

<PARAMARRAY>

The following example shows that the PARAMS elements in the response are not in the same order as in the request:

<PARAMARRAY>

   <PARAMS>
     <SERVICEID>SVC_3</SERVICEID>
     <ACCESS>F</ACCESS>	
   </PARAMS>

   <PARAMS>
     <SERVICEID>SVC_1</SERVICEID>
     <ACCESS>F</ACCESS>	
   </PARAMS>

   <PARAMS>
     <SERVICEID>SVC_2</SERVICEID>
     <ACCESS>F</ACCESS>	
   </PARAMS>

<PARAMARRAY>

Use the service ID value in each PARAMS element to map the sub responses to the sub requests.

See Also

Understanding Code Examples in this Chapter

Reading Validation and Error Information in Response Messages

A MSG element is contained within each PARAMS element when the system must convey validation or error information. For example, if a required element is missing from a request message, such as SERVICE_TYPE, or if an exception has occurred, a MSG element that contains information about the validation or error is included in the response.

The following example shows a response message for the authorization service. The information contained in each MSG element conveys validation or error information for the request:

<?xml version="1.0"?>
<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http:
//schemas.xmlsoap.org/ws/2003/03/addressing/" xmlns:xsd="http://www.w3.org/
2001/XMLSchema/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance/">
  <soapenv:Header xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <wsse:Security soap:mustUnderstand="1" xmlns:soap="http://schemas.xmlsoap.
    org/wsdl/soap/" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401
    -wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>PTDMO</wsse:Username>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <FindAccess xmlns="http://xmlns.oracle.com/Enterprise/Tools/schemas/
     PTCSSecurityReq.v1">

<PARAMARRAY>
   <PARAMS> 
        <SERVICEID>2</SERVICEID> 
        <SERVICE_INSTID/> 
        <ACCESS>F</ACCESS>
        <SERVICE_TYPE>CREF</SERVICE_TYPE>  
        <MSG>Market name is defaulted to 'GBL'</MSG> 
        <MSG>Portal name is defaulted to the default portal EMPLOYEE of the node 
          PT_LOCAL</MSG> 
         <MSG>Invalid Cref</MSG> 
   </PARAMS>

   <PARAMS> 
         <SERVICEID>1</SERVICEID> 
         <SERVICE_INSTID/> 
         <ACCESS>T</ACCESS>
         <SERVICE_TYPE>CREF</SERVICE_TYPE> 
                  <MSG>Market name is defaulted to 'GBL'</MSG> 
         <MSG>Portal name is defaulted to the default portal EMPLOYEE of the node 
           PT_LOCAL</MSG> 
         <MSG>Basic Security Cleared</MSG>
   </PARAMS>
</PARAMARRAY>

 </FindAccess>
</soapenv:Body>
</soapenv:Envelope>

See Also

Understanding Code Examples in this Chapter

Developing the Security Authorization Service Application Class

This section describes how to:

• Develop the authorization service application class.

• Use the Authorization Request object.

Developing the Authorization Application Class

The application class for the authorization service must be created from the base interface PTCS_SECURITY:Security:SecurityHandler. This base interface has only one method, GetAuthorization(), which must be implemented by all child classes. This method receives an array of AuthRequest objects as parameters.

Note. You need develop the security authorization application class when you are performing row-level authorization.

Import PTCS_SECURITY:Security:*;
Class SampleSecurityAppclass extends PTCS_SECURITY:Security:SecurityHandler
   /*method AuthRequestHandler(&arrAuthReq As array of PTCS_SECURITY:Security:*/
   /*AuthRequest);*/
   method GetAuthorization(&arrAuthReq As array of PTCS_SECURITY:Security:AuthRequest);
   
end-class;

/*method AuthRequestHandler*/
method GetAuthorization
   /+ &arrAuthReq as Array of PTCS_SECURITY:Security:AuthRequest +/
   /+ Extends/implements PTCS_SECURITY:Security:SecurityHandler.GetAuthorization +/
   
   Local integer &i;
   Local string &val, &userid;

/* Setting the Access Property in the AuthRequest object */
   For &i = 1 To &arrAuthReq.Len
      &arrAuthReq [&i].Access = "T";
   End-For;
   
/* Reading the Keyvalue from the AuthRequest object */
    &val = &arrAuthReq [1].GetParameterValue("CUSTOMER");

/* Reading the userid from the AuthRequest object */
end-method;

See Also

Understanding Code Examples in this Chapter

Using the Authorization Request Object

The different parameters of an authorization request that are present in each PARAMS element in a request message are encapsulated in an AuthRequest object. The AuthRequest object stores the key values of the request in an array. Use the GetParameterValues method to retrieve a particular value by passing the key name.

The AuthRequest method of the AuthRequest object has an Access property that you use to set the authorization access for the user. A value of T (true) authorizes access and a value of F (false) denies access. The value of the Access property is set to F by default. You can set the property to T from inside the security application class as dictated by business requirements.

Configuring Content References and Components to Use the Security Authorization Service

This section discusses how to:

• Configure content references to use the security authorization service.

• Configure components to use the security authorization service.

Understanding Configuring Content References and Components to Use the Security Authorization Service

When using the authorization service to authorize row-level access to data in a component or content reference, you must configure the content reference or component to use the authorization service.

If you are using the authorization service to provide basic object authorization to a component or content reference you do not need to perform this configuration and you can invoke the authorization service as you would any other service.

Configuring Content References to Use the Security Authorization Service

Use the Authorization Configuration page (PTCAC_AUTH_CONFIG) to map content references to security authorization services.

To access the page, select PeopleTools, Security, Authorization Configuration. The following example shows the sections and fields that appear on the Authorization Configuration page when CREF is the content type. It is the default view of the page:

Note. Note that the Status field is not currently used.

In the Content Reference Details section of the page select the content reference for which to configure for the service and the provider portal on which the content reference being authorized resides.

The Content Reference Details section features a Click here to select Content Reference link that you use to select the content reference. When you click the link the Select a Content Reference page (PTCAC_CRFURL_SELCT) appears as shown in the following example:

Expand and collapse the folders on the page to select a content reference. The page also features an Include hidden Crefs box. Check the box to show and select from hidden content references. When you select a content reference, the system displays the Authorization Configuration page and it populates the component values for the content reference in the Component Details section. The following example shows the Authorization Configuration page after selecting a content reference on the Select a Content Reference page:

The last configuration step is to use the Implementation App Class section of the page to define the details of the application class of the service.

To configure a content reference to use the authorization service:

1. Access the Authorization Configuration page (PeopleTools, Security, Authorization Configuration).

2. In the Content Type section, click the CREF radio button.

3. In the Content Reference Details section:

   1. Click the Click here to Select Content Reference link.

      The Select a Content Reference page appears.

   2. Navigate to and click the content reference to map to the service.

      The Authorization Configuration page appears.

   3. In the Portal Name field, select the provider portal where the authorized content reference resides.

4. In the Implementation App Class section, define the details of the application class for the service:

   1. In the Package Name field enter the package name.

   2. In the Path field enter the path.

   3. In the Class ID field enter the application class ID.

5. Click the Save button.

Configuring Components to Use the Security Authorization Service

If you select Component as the content type, the fields that appear on the page are those with which you work to configure a component to use an authorization service. The following example shows the Authorization Configuration page when the Content Type is set to Component:

Note. Note that the Status field is not currently used.

To configure a component to use the authorization service you must define the information about the component and the application class.

To configure a component to use the authorization service:

1. Access the Authorization Configuration page (PeopleTools, Security, Authorization Configuration).

2. In the Content Type section, click the Component radio button.

3. In the Component Details section:

   1. From the Market drop-down list select a value.

   2. In the Menu Name field enter the name of the menu where the component resides.

   3. In the Component field, enter the name of the component.

4. In the Implementation App Class section, define the details of the application class for the service:

   1. In the Package Name field enter the package name.

   2. In the Path field enter the path.

   3. In the Class ID field enter the application class ID.

5. Click the Save button

Testing and Debugging the Security Authorization Service

Use the following utilities to test and debug the authorization service:

• Handler Tester Utility.

  Use this utility to test the authorization service application class that you develop.

  See Using the Handler Tester Utility.

• Generate SOAP Template Utility.

  Use this utility to test SOAP messages.

  See Using the Generate SOAP Template Utility.