Set Proxies

Configure Proxy Service Settings

Oracle Content Management includes a proxy service, so that you can use REST services that have Cross-Origin Resource Sharing (CORS) limitations or require service account credentials.

The proxy service is a reverse proxy server. It provides a URL to which web browsers connect. The proxy service then acts as an intermediary between the web browser and a remote REST service (or endpoint). The proxy service explicitly adds CORS support to all endpoints and can optionally insert service account credentials to requests coming from web browsers.

If you are using a REST server (or endpoint) that already supports CORS and doesn't require the use of service account credentials, you don't need to register it with the proxy service. You can instead register it directly with the Oracle Cloud REST API for Content Management.

After you sign in to the Oracle Content Management web application as an administrator, click Integrations in the Administration area of the navigation menu.
Under Proxy Service, select Enable.
Using the following steps, define any credentials needed by your endpoints, and define the endpoints you want to use the proxy service.

Credentials

When an endpoint uses a credential, the proxy service adds basic access authentication (via the HTTP Authorization header) to requests made by web browsers. If the browser request already includes the Authorization header, the browser request Authorization header will be used instead of the one in the credential.

This gives you the flexibility to provide a read-only credential for most requests, but allow individual requests to provide their own write-capable authentication as needed.

Providing a credential to an endpoint gives all users of the endpoint the same effective permissions granted to the user defined in that credential. To ensure you don’t inadvertently create a security risk, take the following precautions:

Don’t provide a credential for an endpoint unless absolutely necessary. If possible, let the browser requests provide their own Authorization header instead.
If you must provide a credential, try to use one which has read-only access on the target endpoint.
Limit the allowed methods on the endpoint to what is actually required. Unless absolutely necessary, always disable the PUT, POST, and DELETE methods on an endpoint.
When possible, limit the Target URI for the endpoint to a specific area of functionality. For example, rather than providing the base URI to the full API such as http://example.api/, you might be able to limit it to a specific area such as http://example.api/weather/ (for weather-related requests) or http://example.api/date/ (for date-related requests).

If an endpoint requires credentials, define a credential and select it in the endpoint definition:

Click Create new Credential, and complete the following information.
In the Credential Name box, enter a name for the credential that will make clear to other users what the credential is for (for example, DocsAPIUser).
In the Username box, enter the user that should be used to authenticate all requests with the endpoint.
In the Password box, enter the password for the user you entered.
In the Keywords box, optionally provide space-delimited keywords for the credential. Keywords are purely informational for your own needs and do not alter the functionality of the credential. Keywords can include alphanumeric characters, periods, hyphens, and underscores.

The Keywords field is exposed by the proxy service API and can be viewed by non-administrator users. Never include user names, passwords, API keys, or other sensitive information in the Keywords field.
Click Save.

The new credential is available to use with one or more endpoints. It appears in the Credential drop-down list when you create or edit an endpoint.

Endpoints

Define the remote API endpoint you want to use the proxy service. Click Create new Endpoint, and complete the following information:
1. In the Endpoint Name box, enter a name for the endpoint that will make clear to other users what this endpoint is (for example, Content Management API 1.1).
2. Under Enable Endpoint, select Enabled.
  
  You can disable individual endpoints as necessary, rather than disabling the whole proxy service.
3. Under Secure Endpoint, select Secure Endpoint. You can secure an endpoint by allowing only authenticated user to access the endpoint. If you select this check box, anonymous users are required to authenticate themselves via a sign-in page.
4. In the Path Name box, enter a path name for the endpoint (for example, docs). This will become part of the URL path to access the endpoint (for example, /pxysvc/proxy/docs).
  
  The name must be unique, URL-safe, and lowercase, and it must start with a letter. It can include alphanumeric characters, hyphens, and underscores.
5. In the Target URI box, enter the URI for the endpoint (for example, http:// service.example.com/documents/api/1.1).
6. Under Credential, if necessary, select the credentials to use for this endpoint. This list is populated by the credentials you created using the steps above.
7. Under HTTP Methods, select the HTTP methods you want to enable for this endpoint.
  
  GET and OPTIONS methods are always enabled.
8. In the Keywords box, optionally provide space-delimited keywords for the endpoint. Keywords are purely informational for your own needs and do not alter the functionality of the endpoint. Keywords can include alphanumeric characters, periods, hyphens, and underscores.
  
  The Keywords field is exposed by the proxy service API and can be viewed by non-administrator users. Never include user names, passwords, API keys, or other sensitive information in the Keywords field.
9. Under Additional Headers, you can define multiple custom headers to be sent to the target endpoint. For example:
```
CustomHeader1: Value1
CustomHeader2: Value2
```
  The following example from a debug interface shows all the headers sent to a target:
```
idcs_cloudgate_id: internal_APPID
idcs_client_id: internal_APPID
CustomHeader1: Value1
CustomHeader2: Value2
Authorization: ********
```
  The proxy service will add these headers for each request sent to target URI. They will be part of every request header sent to target URI when a proxy URL is requested.
10. In the Connection Timeout box, enter the maximum number of seconds to wait when trying to make a connection with the target URI.
11. In the Socket Timeout box, enter the maximum number of seconds to wait for a pooled connection in the proxy service.
12. In the Connection Request Timeout box, enter the maximum number of seconds to wait when trying to make a connection with the proxy service.
13. Test your endpoint, by clicking Save and Debug. See Debug Proxy Service Endpoints.
14. When you’re satisfied with the result, click Save and Close.

Add Logged User Data to a Request Through a Secure Proxy Endpoint

You can add user data to an external service call with the Oracle Content Management Proxy.

As a system administrator, you can add user profile information including user ID, full name, and email to an external service call with the Oracle Content Management Proxy. You can secure an endpoint only for authenticated users and proxy automatically passes their profile information to the external system. The external system can then assume that the users are authenticated, and it accesses other systems on their behalf.

An anonymous user is navigated to the sign-in page for authentication if a secured endpoint is configured.

Debug Proxy Service Endpoints

You can quickly test a proxy service endpoint without writing any test code. This can be a valuable tool to see how requests and responses are handled between your web browser, the proxy service, and the target URI of the endpoint.

After defining the endpoint, test it by clicking Save and Debug.

Alternatively, in the list of endpoints, click next to the endpoint you want to debug.

At the top of the Debug Endpoint section, you see the URI mapping, which shows how the endpoint’s local path name is mapped to the target URI of the endpoint. Both the local path and the target URI are links so you can make sure they are pointing to the correct locations.
Optionally, enter a user name and password and additional headers to use for the test request. These credentials will be used in lieu of any credential already set on the endpoint. This enables you to test or verify the use of credentials without making them available to all users of the endpoint.
Optionally, enter additional headers to use for the test request. Enter one header per line, using the standard format Name: Value. For example: Content-Type: application/json.
Select an HTTP method, then provide a complete path for the request.

If you select POST or PUT, in the Data box, enter the content which should be sent in the POST or PUT request body.
Click Submit Request.
In the Debug Result section, expand the panels to see the detailed results:
- Browser Request to Proxy: Displays the HTTP request headers and body sent by the web browser to the proxy service.
- Proxy Request to Endpoint: Displays the HTTP request headers and body sent by the proxy service to the target URI of the endpoint. If the endpoint uses a credential, an authorization header is inserted in the request, but the header value isn’t shown in the debug results.
- Endpoint Response to Proxy: Displays the HTTP response headers and body sent by the target URI of the endpoint back to the proxy service.
- Proxy Response to the Browser: Displays the HTTP response headers sent by the proxy service back to the web browser. If the target URI of the endpoint doesn’t return CORS headers, the proxy service inserts them in its response to the browser.
If necessary, change the debug request and submit the request again.

Note:
The old debug results are overwritten with the new results.
When you’re satisfied with the result, click Close.