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.

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.

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

Element

Usage

Comments

SERVICEID

Differentiates different requests in the incoming message.

Required element.

This element is also used to map request messages to response messages, and is particularly useful for mapping sub-requests to sub-responses.

SERVICE_INSTID

Used by PeopleTools internally when multiple instances of the service are used.

Optional element.

SERVICE_TYPE

Service type for which authorization is required.

Required element.

Valid values are:

  • CREF. Content reference.

  • UPGE. Component.

  • PEP. Pagelet. (Embedded).

  • POP. Pagelet.

  • UQRY. Query.

  • USCR. iScript.

If none of the valid values are defined for the SERVICE_TYPE element in the request message an “Invalid Service Type” message appears in the response message.

NODE

Name of the service provider.

Optional element.

When specified the value is passes to the authorization application class. It does not play any other role in determining the security.

CREFID

Content reference ID for the content reference for which authorization is needed.

Required element for service type CREF.

This element is used to get the CREF authorization in the FindCrefById() function.

MENU

Menu name of the component.

Required element for service type UPGE.

COMPONENT

Component name.

Required element for service type UPGE

COMP_ITEM_NAME

Item name of the component.

Optional element.

The process the system uses to derive this value if one is not specified is described elsewhere in this topic.

See Request Messages for Authorizing Access to Components.

See Implementing a Security Authorization Handler

MARKET

Market name of the transaction.

Optional element.

If this element is empty or if a node is not supplied, the value of this field defaults to GBL, (global).

PORTAL

Portal name of the provider system.

Optional element used for the following service types:

  • CREF.

  • UPGE.

If no value is defined for this element or if there is no value defined for the NODE element, the default portal of the default node is used as the value.

KEYVAL

Key/value pairs to pass to the authorization service.

Optional element use for the following service types to authorize row-level security access:

  • CREF.

  • UPGE.

The system uses this element mainly in data security to pass parameters to the Authorization class. It can also be used in basic authorization to send the action mode.

Use key/value pairs in the following scenarios:

  • Pass key/value pairs to the service.

  • In the Related Content framework, use this element to specify keys of a component.

  • In the Related Content framework and other cases, use this element to pass an action mode, using the key value ACTION.

There can be one or more values for each KEYVAL element. For example:

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

Note: The value must not contain more than one equal sign (=). If more than one equal sign is specified for the element an error occurs and the system returns a message element (MSG) containing the message “Invalid Keyval value.”

For UPGE service types only, a special key/value with the key name ACTION is available through which action mode can be passed. The ACTION key/value specifies the action mode in which to check the authorization.

For the Related Content framework this value is passed as a service element as follows:

<KEYVAL>ACTION=U<KEYVAL>

The valid values for the ACTION element are:

  • A, Add.

    Constant value: %Action_Add

  • U. Update/Display.

    Constant value: %Action_UpdateDisplay

  • L. Update/Display All.

    Constant value: %Action_UpdateDisplayAll

  • C. Correction.

  • E. Data entry.

    Constant value: %Action_DataEntry

If you do not define a value for this element the systems ascertains in what mode, of all the available modes, the user has access to the component. If the user has access in multiple modes, the systems uses the mode with the greatest privilege. Though it makes no difference while determining the authorization, it will be of use inside the security application class , into which the action mode is passed via the Authorization Request object.

PAGELETID

Pagelet ID of the pagelet.

Required element for the following service types:

  • PEP.

  • POP.

In cases where the pagelet ID is not available but the content reference ID (CREFID) is available, you can authorize pagelet access by selecting CREF as the service type and specify the CREFID of the pagelet.

QUERY

Query name.

Required element for service type UQRY.

RECORD

iScript record name.

Required element for service type USCR.

FIELD

iScript field name.

Required element for service typeUSCR.

FUNCTION

iScript function name.

Required element for service typeUSCR.

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.

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>

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.

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.

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.