4 Credentials

You still need database credentials to access RDS through your private endpoint. You obtain these credentials by using the Credential Exchange Service, a REST endpoint.

The endpoint provides a means of fetching the database credentials required to connect. Credentials are periodically refreshed when passwords are rotated. You receive notification of password rotation by registering one or more callback services or email addresses with the Credential Exchange Service. Any callback service should be accessible through the Private Endpoint. Repeatedly unavailable endpoints may be removed. Finally, credentials are not conveyed through the callback; you are only notified that they have changed.

Expect Oracle support to contact you on the details of the Credential Exchange Server base URL. The host port of the base URL is 443.

The Credential Exchange Service uses OAUTH 2 for authentication. That token is generated using a well-known OCI IAM service, which authenticates using basic auth. The basic auth credentials (i.e., client id and client secret) are obtained from Retail Home. See Section 4.3.2: Obtaining ORDS Services Credentials for more details. The process is the same.

Bear in mind, the OCI IAM service is rate limited (see API Rate Limits). Best practice is to reuse tokens until they expire (one hour). If you encounter a 429 error when requesting a token or authenticating, you have hit the rate limit. When you encounter a rate limit, back off for one minute to reset the rate limiter.

Credential Exchange Endpoints

Fetching Credentials

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

Returns the wallet and credentials for the schemas exposed by the Database Private Endpoint.

The JSON format of the response is detailed in a following section.

Fetching Wallet

Method	Endpoint
GET	https://<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 fetch-credentials endpoint.

Registering Notification Endpoints

Method	Endpoint
PUT	https://<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 form of http, https, or mailto (e.g., mailto:[e-mail]).

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.

Method	Endpoint
DELETE	https://<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.

Method	Endpoint
GET	https://<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: [e-mail]" ] }

Serialized Wallet and Credential Format

Credentials are serialized into JSON and, within that payload, Oracle Wallet file contents are base64 encoded.

Content	Purpose
wallets	Array of wallets, currently a single entry
walletName	Name of database wallet and instance, derived from tnsnames.ora within wallet
walletPassword	(Currently unused)
comment	(Currently unused)
certificateEndDate	Expiration date of wallet, derived from truststore certificate within wallet
certificateStartDate	Start date of wallet, derived from truststore certificate within wallet
lastRotationDate	Date of last rotation
schemas	Map of database credentials (username):(password)
wallet	Map of wallet file contents, (filename):(base64 encoded file)

Example

{
  "wallets": [
    {
      "certificateEndDate": 1746276157000,
      "certificateStartDate": 1588596157000,
      "comment": null,
      "lastRotationDate": 1624305815466,
      "schemas": {
        "username1": "password1",
        "username2": "password2",
        "username3": "password3",
        "username4": "password4",
      },
    "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
   }
  ]
}