PeopleSoft Integration Broker: Secure REST Service Publishing with OAu

Learn to publish PeopleSoft Integration Broker REST services with OAuth 2.0. Implement secure API authentication for robust integrations.

Overview

In the evolving landscape of enterprise applications, integrating disparate systems efficiently and securely is paramount. Oracle PeopleSoft, a cornerstone for many organizations' HR, Finance, and Campus Solutions, has long provided robust integration capabilities through its Integration Broker (IB). While IB supports various protocols including SOAP, JMS, and File Layouts, the demand for lightweight, flexible, and web-friendly integrations has made RESTful services increasingly popular.

Publishing REST services from PeopleSoft Integration Broker allows external systems, mobile applications, and other microservices to interact with PeopleSoft data and business processes using standard HTTP methods and JSON/XML payloads. However, exposing critical enterprise data requires stringent security measures. This is where OAuth 2.0 steps in, providing a robust authorization framework to secure these RESTful APIs, ensuring that only authorized clients and users can access PeopleSoft resources.

OAuth 2.0 is an industry-standard protocol for authorization. It allows a user to grant a third-party application limited access to their resources on another server, without sharing their credentials. Instead, the third-party application receives an access token, which is then used to access the protected resources. In the context of PeopleSoft, the Integration Broker acts as the resource server, validating access tokens issued by an Authorization Server to grant or deny access to its published REST services.

This article will guide you through the process of publishing a REST service in PeopleSoft Integration Broker and securing it using OAuth 2.0. We will cover the necessary configurations, delve into the security implications, and provide best practices to ensure your PeopleSoft integrations are both powerful and protected.

Prerequisites

Before embarking on the implementation, ensure you have the following in place:

PeopleSoft Environment: A functional PeopleSoft 9.2 application environment (preferably PUM Image 30 or higher for the latest IB and OAuth features).
Integration Broker Configuration: Integration Broker must be configured and active. This includes ensuring the Integration Gateway is running, the default local node is set up, and the ANONYMOUS node has appropriate permissions.
Application Designer Access: Developer access to PeopleSoft Application Designer for creating and modifying service operations and PeopleCode.
PeopleSoft Administrator Access: Permissions to configure Integration Broker setup pages and OAuth 2.0 profiles within the PeopleSoft PIA.
Basic REST Knowledge: Familiarity with REST architectural principles, HTTP methods (GET, POST, PUT, DELETE), and JSON/XML data formats.
OAuth 2.0 Authorization Server: An external OAuth 2.0 Authorization Server (e.g., Oracle Identity Cloud Service (IDCS), Keycloak, Auth0, Okta, or a custom implementation) that can issue access tokens. PeopleSoft will act as the Resource Server and will validate tokens issued by this Authorization Server. You will need the Issuer ID, Audience, and either an Introspection URL or JWKS URL from this server.
Testing Tools: A tool like Postman, Insomnia, or curl for testing REST API calls.

Step-by-Step Implementation

1. Create a REST Service Operation in Application Designer

First, we need to define the service operation that will expose our PeopleSoft functionality as a REST service.

Open Application Designer: Log in to Application Designer.
Create a New Service Operation: Go to File > New > Service Operation.
Define Service Operation Properties:
- Service Operation Name: Choose a descriptive name, e.g., GET_USER_PROFILE.
- Service Name: Create a new service or select an existing one, e.g., USER_SERVICES.
- Message Type: Select Non-Rowset REST. This is crucial for REST services that don't conform to the PeopleSoft rowset structure.
- Request Message: For a simple GET, you might use UNSTRUCTURED or ANY. For POST/PUT, define a message record or use UNSTRUCTURED/ANY if handling raw JSON/XML.
- Response Message: Similar to Request Message, use UNSTRUCTURED or ANY for flexible JSON/XML responses.
- Default Version: VERSION_1.
- HTTP Method: Select the appropriate method (e.g., GET for retrieving data).
Save the Service Operation.

Write PeopleCode for the OnRequest Handler:

This is where your business logic resides. For a GET_USER_PROFILE service, you might retrieve user data based on a path parameter or query string. PeopleSoft Integration Broker automatically parses the URL and makes path parameters and query string parameters available via the %IntBroker object.

Example PeopleCode for GET_USER_PROFILE (assuming a path parameter like /users/{OPRID}):


Declare Function getProfileData PeopleCode FUNCLIB_REST.FUNCLIB FieldFormula;

Local PSMessage &msg;
Local string &oprid;
Local string &jsonOutput;
Local string &responseStatus;
Local string &responseReason;
Local integer &responseCode;

&msg = %IntBroker.ReceivedMessage;

/* Extract OPRID from the REST URL path parameter */
/* Assuming the URL pattern is /users/{OPRID} */
If &msg.Has  Path  Parameters Then
   &oprid = &msg.GetPathParameter("OPRID");
Else
   /* Handle error if OPRID is not provided in path */
   Local PT_JSON:JSONParser &parser = create PT_JSON:JSONParser();
   Local PT_JSON:JSONObject &jsonObject = &parser.Parse("{""error"":""OPRID not provided in URL path.""}");
   &msg.SetXmlDoc(&jsonObject.ToString());
   %IntBroker.Set and ClearIBInfo(False);
   %IntBroker.SetHttpError(400, "Bad Request");
   Return;
End-If;

If All(&oprid) Then
   /* Call a function or write inline code to fetch user profile data */
   /* For demonstration, let's create a dummy JSON response */
   Local SQL &sql;
   Local string &firstName, &lastName, &email;

   &sql = CreateSQL("SELECT A.FIRSTNAME, A.LASTNAME, B.EMAILID FROM PS_NAMES A, PS_EMAIL_ADDRESSES B WHERE A.EMPLID = B.EMPLID AND A.EFFDT = (SELECT MAX(A_ED.EFFDT) FROM PS_NAMES A_ED WHERE A.EMPLID = A_ED.EMPLID AND A_ED.EFFDT <= %CurrentDateIn) AND B.EMAIL_TYPE = 'BUS' AND A.OPRID = :1", &oprid);

   If &sql.Fetch(&firstName, &lastName, &email) Then
      Local PT_JSON:JSONParser &parser = create PT_JSON:JSONParser();
      Local PT_JSON:JSONObject &jsonObject = create PT_JSON:JSONObject();
      &jsonObject.Put("oprid", &oprid);
      &jsonObject.Put("firstName", &firstName);
      &jsonObject.Put("lastName", &lastName);
      &jsonObject.Put("email", &email);
      &jsonObject.Put("status", "active");
      &jsonOutput = &jsonObject.ToString();

      &msg.SetXmlDoc(&jsonOutput);
      %IntBroker.SetHttpContentType("application/json");
      %IntBroker.SetHttpError(200, "OK");
   Else
      Local PT_JSON:JSONParser &parser = create PT_JSON:JSONParser();
      Local PT_JSON:JSONObject &jsonObject = &parser.Parse("{""error"":""User not found for OPRID: " | &oprid | """}");
      &msg.SetXmlDoc(&jsonObject.ToString());
      %IntBroker.SetHttpContentType("application/json");
      %IntBroker.SetHttpError(404, "Not Found");
   End-If;
Else
   Local PT_JSON:JSONParser &parser = create PT_JSON:JSONParser();
   Local PT_JSON:JSONObject &jsonObject = &parser.Parse("{""error"":""Invalid OPRID provided.""}");
   &msg.SetXmlDoc(&jsonObject.ToString());
   %IntBroker.SetHttpContentType("application/json");
   %IntBroker.SetHttpError(400, "Bad Request");
End-If;

%IntBroker.Set and ClearIBInfo(False);

Save the PeopleCode to the OnRequest event of the Service Operation.

2. Configure the Service Operation in Integration Broker

Now, we configure the service operation in the PeopleSoft PIA to make it accessible via Integration Broker.

Navigate to Service Operations: Go to PeopleTools > Integration Broker > Integration Setup > Service Operations.
Search for your Service Operation: Find GET_USER_PROFILE.
General Tab:
- Active: Check this box.
- Default Version: VERSION_1.
- Service Operation Type: Asynchronous (for REST, it's typically treated as synchronous from the client's perspective, but IB processes it asynchronously).
- Inbound Asynchronous and Outbound Asynchronous: Enable as needed. For publishing a service, Inbound is primary.
- Security: Initially, leave it as None or User/Password. We will change this to OAuth 2.0 later.
Handlers Tab:
- Click Add Handler.
- Handler Type: OnRequest.
- Handler Name: The Application Class where your PeopleCode resides (e.g., IB_SERVICE:REST:GET_USER_INFO, assuming your App Class path).
- Active: Check this box.
- Save.
Routings Tab:
- Click Add New Routing.
- Routing Type: Inbound.
- Sender Node: ANONYMOUS (or a specific node if you want to restrict which nodes can call this service).
- Receiver Node: Your local node (e.g., PSFT_HR).
- External Alias: This defines the URL path for your REST service. For GET_USER_PROFILE, you might set it to users/{OPRID}. This maps to the path parameter defined in your PeopleCode.
- Active: Check this box.
- Save.
REST Tab:
- Ensure HTTP Method matches what you defined (e.g., GET).
- URL Resource Identifier: This should match your External Alias, e.g., /users/{OPRID}.
- Default Request Message Type: JSON (or XML, TEXT as appropriate).
- Default Response Message Type: JSON.
- Save.

3. Configure OAuth 2.0 Profile in PeopleSoft

This step involves telling PeopleSoft how to validate OAuth 2.0 access tokens.

Navigate to OAuth 2.0 Profiles: Go to PeopleTools > Security > OAuth 2.0 > OAuth 2.0 Profile.
Create a New Profile: Click Add a New Value.
- Profile Name: A descriptive name, e.g., TECHNEWS_OAUTH_PROFILE.
- Click Add.
Configure Profile Details:
- Description: Provide a clear description.
- Issuer ID: This is the unique identifier of your OAuth 2.0 Authorization Server. Example: https://idcs-xxxxxxxxxxxxx.identity.oraclecloud.com/oauth2/v1/
- Audience: This identifies the recipient of the access token, which is PeopleSoft acting as the Resource Server. Example: peoplesoft.api.tech_news (This should be configured on your Authorization Server as an audience for tokens intended for PeopleSoft).
- Validation Method:
  - Introspection: PeopleSoft will call the Authorization Server's introspection endpoint to validate the token.
  - JWKS (JSON Web Key Set): PeopleSoft will fetch public keys from the JWKS endpoint to validate the token locally. This is generally preferred for performance as it avoids a network call for every token validation once keys are cached.
  For this example, let's assume we are using JWKS for performance.
- Role Mapping: (Optional but highly recommended) You can map OAuth scopes or claims from the access token to PeopleSoft roles.
  - Click Add Row under Role Mapping.
  - Claim Name: Usually scope or a custom claim from your Authorization Server.
  - Claim Value: A specific scope value, e.g., peoplesoft.users.read.
  - PeopleSoft Role: A PeopleSoft role that users with this scope should inherit, e.g., PPLSOFT_REST_USER. (Ensure this role has appropriate permissions to execute the service operation).
- Save the OAuth 2.0 Profile.

4. Link OAuth 2.0 Profile to the Service Operation

Now, we secure our previously created service operation using the defined OAuth 2.0 profile.

Navigate to Service Operations: Go to PeopleTools > Integration Broker > Integration Setup > Service Operations.
Search for your Service Operation: Find GET_USER_PROFILE.
General Tab:
- Under the Security section, change the dropdown from None (or whatever it was) to OAuth 2.0.
- OAuth 2.0 Profile: Select the profile you just created, e.g., TECHNEWS_OAUTH_PROFILE.
- Required Scopes: Enter the specific OAuth scopes that an access token *must* contain for this service operation to be authorized. Example: peoplesoft.users.read. Multiple scopes can be space-separated.
- Save the Service Operation.

5. Test the REST Service with OAuth 2.0

Finally, it's time to test our secure REST service.

Obtain an Access Token:
You need to get a valid access token from your OAuth 2.0 Authorization Server. The method varies based on the grant type (e.g., Client Credentials, Authorization Code, Implicit, etc.). For testing, you might use the Client Credentials Grant if your client is a confidential application, or an Authorization Code Grant if simulating a user login.

Example using curl for Client Credentials Grant (replace placeholders with your actual values):
```
curl -X POST \
  https://idcs-xxxxxxxxxxxxx.identity.oraclecloud.com/oauth2/v1/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  -d 'grant_type=client_credentials&scope=peoplesoft.users.read'
```
This will return a JSON response containing your access_token.
```
{
    "access_token": "eyJraWQiOiJvcmFjb...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "peoplesoft.users.read"
}
```
Copy the access_token value.

Call the PeopleSoft REST Service:

Use curl or Postman to call your PeopleSoft REST service, including the obtained access token in the Authorization header.

The full URL for your service operation will typically be in the format: http://<PIA_SERVER>:<PORT>/PSIGW/RESTListeningConnector/<NODE_NAME>/<SERVICE_ALIAS_PATH>.

Example curl command:


curl -X GET \
  'http://mypia.example.com:8000/PSIGW/RESTListeningConnector/PSFT_HR/users/VP1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJraWQiOiJvcmFjb...'

Expected Success Response (HTTP 200 OK):


{
    "oprid": "VP1",
    "firstName": "VP1",
    "lastName": "User",
    "email": "vp1@example.com",
    "status": "active"
}

Expected Failure Response (without token or invalid token - HTTP 401 Unauthorized):


{
    "error": "Unauthorized",
    "error_description": "Full authentication is required to access this resource."
}

Expected Failure Response (valid token but missing required scope - HTTP 403 Forbidden):


{
    "error": "Forbidden",
    "error_description": "Access token does not have the required scopes."
}

Security Considerations

Securing REST services is a multi-layered effort. While OAuth 2.0 handles authorization, several other aspects must be carefully managed:

Transport Layer Security (TLS/HTTPS): Always, without exception, expose your PeopleSoft Integration Broker over HTTPS. This encrypts all communication between the client and PeopleSoft, protecting access tokens and sensitive data from interception. Configure your web server (e.g., Oracle HTTP Server, WebLogic) to enforce HTTPS.
Robust OAuth 2.0 Authorization Server: The security of your entire system heavily relies on the Authorization Server. Ensure it is well-secured, regularly patched, and compliant with security best practices (e.g., strong password policies, multi-factor authentication for administrative access, regular audits).
Token Validation Mechanism (JWKS vs. Introspection):
- JWKS: Offers better performance as token validation is done locally after fetching public keys. However, it means PeopleSoft cannot immediately detect token revocation if the token is valid according to the signature but has been revoked on the Authorization Server. Cache invalidation for JWKS should be carefully managed.
- Introspection: Guarantees real-time token status, including revocation. The trade-off is a network call to the Authorization Server for every token validation, which can introduce latency and be a performance bottleneck under high load. Choose based on your security and performance requirements.
Scope Management: Define granular scopes that precisely reflect the permissions needed for each service operation. Avoid overly broad scopes. Regularly review and refine your scope definitions.
Token Expiration and Refresh Tokens: Access tokens should have a short lifespan (e.g., 15-60 minutes) to minimize the window of opportunity for token misuse if compromised. Implement refresh tokens (if applicable to your OAuth flow) to allow clients to obtain new access tokens without re-authenticating the user, while still allowing the Authorization Server to revoke access when needed.
Input Validation and Sanitization: Even with OAuth 2.0 protecting access, your PeopleCode handlers must rigorously validate and sanitize all incoming data to prevent injection attacks (SQL injection, XSS if responses are rendered directly) and ensure data integrity.
Error Handling: Provide generic error messages to external clients, avoiding sensitive information disclosure in error responses. Use appropriate HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error).
Logging and Monitoring: Implement comprehensive logging for API access, token validation attempts, and any security-related events. Monitor these logs for suspicious activity, failed authorization attempts, or unusual traffic patterns.
Least Privilege Principle: Ensure that the PeopleSoft user ID associated with the Integration Broker gateway (often PSIGW) and the roles mapped via OAuth have only the minimum necessary permissions to perform their designated tasks. Do not grant broad administrator privileges.
DDoS Protection: Implement measures to protect your Integration Broker endpoints from Denial-of-Service (DoS) and Distributed Denial-of-Service (DDoS) attacks. This may involve network-level protections, rate limiting, and Web Application Firewalls (WAFs).

Best Practices

To build robust and maintainable PeopleSoft REST services with OAuth 2.0:

API Versioning: Implement API versioning (e.g., /v1/users, /v2/products) to manage changes and ensure backward compatibility for existing clients. This is typically done through the external alias of your service operation.
Consistent Error Responses: Design a consistent and predictable error response format (e.g., JSON with error_code, message fields) across all your REST services.
Comprehensive Documentation: Document your REST APIs thoroughly. Use tools like OpenAPI (Swagger) to generate interactive documentation. PeopleSoft can generate WADL, but OpenAPI is more widely adopted for REST.
Statelessness: Adhere to REST's stateless principle. Each request from a client to the server must contain all the information needed to understand the request. The server should not store any client context between requests.
Idempotency: Design PUT and DELETE operations to be idempotent, meaning that making the same request multiple times has the same effect as making it once. GET operations are inherently idempotent.
Performance Optimization:
- Optimize PeopleCode logic to minimize database calls and complex computations.
- Implement effective caching strategies where appropriate (e.g., for static lookup data).
- Monitor Integration Broker performance and tune application server and web server settings.
Centralized OAuth Provider: Leverage a dedicated, robust OAuth 2.0 Authorization Server rather than attempting to implement one within PeopleSoft. This offloads identity and access management complexities to specialized systems.
Regular Audits: Periodically review your OAuth 2.0 profiles, service operation security settings, and PeopleCode handlers for potential vulnerabilities or outdated configurations.
Use Standard Libraries for JSON/XML: Leverage PeopleSoft's built-in PT_JSON or PT_XML application classes for parsing and generating JSON/XML payloads. Avoid manual string manipulation for complex structures.

FAQ

Q1: What if my Authorization Server doesn't support JWKS or Introspection?

A1: While most modern OAuth 2.0 Authorization Servers support either JWKS or Introspection (or both), if yours doesn't, you would typically need a custom solution. This would involve writing PeopleCode to manually validate the token. This could mean decoding a JWT (if it's a JWT) and verifying its signature and claims against known keys/values, or making a custom API call to your Authorization Server's validation endpoint. This approach increases complexity and maintenance overhead and should only be considered if standard methods are absolutely unavailable. It's generally recommended to choose an Authorization Server that adheres to common OAuth 2.0 specifications.

Q2: How can I map OAuth scopes to PeopleSoft roles or permissions more dynamically?

A2: The PeopleSoft OAuth 2.0 Profile allows direct mapping of specific OAuth claims (like scope values) to PeopleSoft roles. If you need more dynamic or granular mapping, you could enhance your PeopleCode handler. Upon successful token validation by Integration Broker, you can access the token's claims (via %IntBroker.ReceivedMessage.GetOAuthClaim()). You could then write PeopleCode to:

Read specific claims (e.g., a custom claim for 'department' or '

PeopleSoft Integration Broker: Secure REST Service Publishing with OAuth 2.0