4 Credentials
Database credentials are needed to access Retail AI Foundation Cloud Service through your private endpoint. Obtain these credentials by using the Credential Exchange Service, a REST endpoint, through its own private endpoint.
The endpoint provides a means of fetching the database credentials required to connect. Credentials are periodically refreshed when passwords are rotated. Notification of password rotation is received by registering one or more callback services or email addresses with the Credential Exchange Service.
It is recommended that at least an email address be registered through the rotation-notification endpoint as a fallback means of notification, otherwise the credentials may be rotated without your knowledge.
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.
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.
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 an HTTP- 429 error when requesting a token or authenticating, you have hit the rate limit. When you encounter a rate limit, pause any further requests for one minute to reset the rate limiter.
Credential Exchange Endpoints
Fetching Credentials
Method | Endpoint |
---|---|
GET |
/api/data-pe/v1/fetch-credentials |
Returns the wallet and credentials for the schemas exposed by the Database Private Endpoint.
Fetching Wallet
Method | Endpoint |
---|---|
GET | /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 |
/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: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>"
}
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 |
/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 |
/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" ] }
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 |
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
}
]
}
Table 4-1 Troubleshooting
HTTP Status Code | Problem | Solution |
---|---|---|
404 | Incorrect API URL | Verify API URL |
401 | Invalid, expired, or missing token | Verify that you are using the a client ID and secret from the correct IAM service, that the token has not expired, that the token is valid (e.g., echo cURL script), and the token is not missing. |
403 | Internal error | Submit a support ticket with the details of the API invocation (e.g., a cURL script) |
200 | Response is: {"msg":"Internal error, cannot connect to upstream service", "detail":"java.net.ConnectException: Connection refused (Connection refused)"} | Submit a support ticket with the details of the API invocation (e.g., a cURL script) |