Mirror of Oracle documentation

Converted for search and offline reading. Authoritative source: Oracle. Diagrams and some complex tables are simplified — check the PDF when in doubt.

5 Credential Exchange Service API

Base URL

The base URL of the Credential Exchange Service (CES) can be obtained from your Oracle Retail Home endpoint. If you do not know your Oracle Retail Home endpoint, contact your administrator.

The Oracle Retail Home endpoint has the following format:

https://home.retail.<region>.ocs.oracle.com/<sub-namespace-name>

The sub-namespace-name can be further decomposed into:

rgbu-common-<customerID>-<env>-rh

You can extract region, customerID, and env from your Oracle Retail Home URL. The host port of the base URL is 443. The base URL for the CES is:

https://home.retail.<region>.ocs.oracle.com:443/rgbu-common-<customerID>-<env>

If you are still uncertain as to how to construct the base URL or the base URL you have constructed is not working as expected, submit a Support Request for further assistance.

On-Premises Access

If you are accessing the Credential Exchange Service from on-premises, you need to ensure that network connectivity to the CES private endpoint is in place. This typically requires:

Private connectivity (such as Oracle FastConnect or a VPN) between your on-premises network and the Oracle Cloud Infrastructure (OCI) Virtual Cloud Network (VCN) where the CES Private Endpoint resides.
Ingress rules on the subnet security list or Network Security Groups (NSGs) that allow traffic from your on-premises IP range to the CES Private Endpoint over TCP port 443 .
DNS resolution of the home.retail.<region>.ocs.oracle.com domain to the private IP address of the CES endpoint. This may involve a custom DNS resolver rule in OCI or DNS forwarding from your on-premises network.

Contact your organization’s network and cloud administrators to confirm that all required routing, security, and DNS configurations are in place to support private access to CES from on-premise systems.

Credential Exchange Service Endpoints

To access the CES, your PE subnet’s VCN must be attached to a service gateway that forwards traffic to the Oracle Services Network. The credential CES API only accepts the traffic from the Private Network. Access from a Public Network will result in an HTTP 401 Status (Forbidden).

When you fetch credentials as JSON or a wallet ZIP file to an OCI VM as described in the examples, you need to copy it to your on-premises system.

Fetching Credentials

Method	Endpoint
GET	`<base-url>/api/data-pe/v1/fetch-credentials`

Returns the wallet and credentials for the schemas exposed by the Database Private Endpoint. Credentials are serialized into JSON and, within that payload, Oracle Wallet file contents are base64 encoded. The JSON format of the response is shown below.

JSON Format of Wallet and Credentials

{
   "wallets": {
   "certificateEndDate": 1746276157000,
   "certificateStartDate": 1588596157000,
   "comment": null,
   "lastRotationDate": 1624305815466,
   "schemas": {
   "MFCS_RDS_CUSTOM": "password1",
   "CE_RDS_CUSTOM": "password2",
   ...
   “RASE01": "password3",
   “RABE01USER": "password3"
   },
   "wallet": {
                     "README": "...base64-encoded-file...",
                     "cwallet.sso": "...base64-encoded-file...",
                     "ewallet.p12": "...base64-encoded-file...",
                     "keystore.jks": "...base64-encoded-file...",
                     "ojdbc.properties": "...base64-encoded-file...",
                     "sqlnet.ora": "...base64-encoded-file...",
                     "tnsnames.ora": "...base64-encoded-file...",
                     "truststore.jks": "...base64-encoded-file..."
                    },
       "walletName": "Wallet_RDSADWABC123",
       "walletPassword": null
       }
}

Table 5-1 Serialized Wallet and Credential Format

Content	Purpose
wallets	Map of the wallet contents
walletName	Name of the database wallet and instance, derived from tnsname.ora within the wallet
walletPassword	(currently unused)
comment	(currently unused)
certifcateEndDate	Expiration date of the wallet, derived from the truststore certifcate within the wallet

Table 5-1 (Cont.) Serialized Wallet and Credential Format

Content	Purpose
certifcateStartDate	Start date of the wallet, derived from the truststore certifcate within the wallet
lastRotationDate	Date of last rotation
schemas	Map of the database credentials, (username):(password)
wallet	Map of the wallet fle contents, (flename):(base64 encoded fle)

Fetching the Wallet

Method	Endpoint
GET	`<base-url>/api/data-pe/v1/fetch-wallet`

This REST call returns the wallet as a compiled zip file for use with the Database Private Endpoint. The wallet does not contain credentials; these need to be fetched from the fetchcredentials endpoint.

Notification Endpoints

Registering Notification Endpoints

Method	Endpoint
PUT	`<base-url>/api/data-pe/v1/rotation-notification`

JSON Payload: {"usecase": "credentialRotationNotification", "endpoint": "http:// example.org:80/foo/bar/baz/notification1" }

This method inserts unique endpoints into the notification endpoint list. Duplicates are silently ignored (intended for repeat registrations from restarted callback services). The notification endpoint can be a URL in the format of HTTP, HTTPS, or MAILTO (for example, mailto:foo@bar.baz).

Registered HTTP or HTTPS endpoints are called with an HTTP POST containing a JSON payload describing the scope of the change: {usecase:"credentialRotation", change:"<all|credentials|wallet>" }

Note

If an HTTP or HTTPS endpoint is registered, you may need to add an ingress rule for <base_url> to ensure that the endpoint is reachable.

Registered MAILTO endpoints are sent a notification email. SMTP notifications are sent from the regional OCI Email Delivery Service to the email address that the customer specifies.

After receiving this notification, the consuming applications should refresh their credentials using the fetch-credentials or fetch-wallet endpoints.

Unregistering Notification Endpoints

Method	Endpoint
DELETE	`<base-url>/api/data-pe/v1/rotation-notification`

JSON Payload: {"usecase": "credentialRotationNotification", "endpoint": "http:// example.org:80/foo/bar/baz/notification1" }

Removes endpoints from a list. Non-existent endpoints are silently ignored.

Listing Notification Endpoints

Method	Endpoint
GET	`<base-url>/api/data-pe/v1/rotation-notification?`
	`tenantId=abc123`

Returns endpoints[…] containing a list of registered endpoints, or empty endpoints [] if none exist.

Example:

{"endpoints": [ "http://example.org:80/foo/bar/baz/notification", "mailto:
nobody@example.org" ] }

Troubleshooting

Table 5-2 HTTP Status Code

Problem	Solution
404	Incorrect API URL. Verify API URL.
401	Invalid, expired, or missing token. Verify that you are using a client ID and secret from the correct IAM service, that the token has not expired, that the token is valid (for example, echo CURL script), and the token is not missing.
403	Internal error. Submit a support ticket with the details of the API invocation (for example, a cURL script).
200	Response is: {“msg”:”Internal error. Cannot connect to upstream service”. “detail”:”java.net.ConnectException: Connection refused (Connection refused)”}

In this guide

Guide: AIF Private Endpoint - Database Access Implementation Guide
Previous: 4 Access Setup for the Credential Exchange Service
Next: 6 Verifying your Private Endpoint from an OCI VM

Oracle Retail Knowledge Base

Explorer

5 Credential Exchange Service API

Base URL

On-Premises Access

Credential Exchange Service Endpoints

Fetching Credentials

JSON Format of Wallet and Credentials

Fetching the Wallet

Notification Endpoints

Registering Notification Endpoints

Note

Unregistering Notification Endpoints

Listing Notification Endpoints

Example:

Troubleshooting

In this guide

Graph View

Table of Contents

Backlinks