Oracle Analytics Cloud on a Private Network — Part Two

Data sources, the front door, the evidence, and the hand-over

Part two of two, continuing from Oracle Analytics Cloud on a Private Network — Part One. Chapter, figure and table numbering continue without a reset, so a reference below to chapter 21, to figure 14, or to Parts I to IV points into the first article and means the same thing there. The appendices at the end of this article cover both halves.

Where part one left off

The first article established four things that everything below depends on, and they are worth restating in a paragraph each, because the second half is unreadable without them.

Two planes, with separate enforcement. The cloud console creates, sizes, networks and logs the instance and enforces IAM policy on the resource. The product console holds application roles, catalogue permissions, connections and the semantic model. The two are distinct, and an authorization decision made on one is not enforced on the other — the documented junction between them is the membership of identity-domain service roles in specific in-product application roles. A person can hold complete authority on one plane and none on the other, and each console will report a coherent, partial picture. Every hand-over checklist is written twice.

Edition decides the data path. The private access channel exists only on Enterprise edition, and the edition is changeable from the Console’s Actions menu although the supported directions are not fully documented. Together with the endpoint model, the identity domain, the region and the update cycle — all fixed at creation — that makes provisioning a set of decisions rather than a form.

Ingress and egress are different problems. The private endpoint terminates browser traffic and initiates nothing. Data connections leave from the channel, which is a name-matched policy rather than a route: anything not matching a registered DNS zone leaves from a regional gateway address that is not yours. Eight addresses are mandatory in the analytics subnet before a query runs; a ninth is consumed only if a private-source endpoint is deliberately colocated.

Authorization has six levels, three administrative surfaces, and no page that shows them together. Two of the six are administered outside the identity domain entirely. Each level is granted, revoked and audited on its own surface, and exactly one documented membership edge crosses between them — level 2 into level 3. The privilege that lets a delivery identity administer the product is not an IAM policy and is not revoked by removing one.

The product names are those of the deployment, as in chapter 2 of the first article: Oracle renamed Autonomous Data Warehouse to Oracle Autonomous AI Lakehouse and Autonomous Transaction Processing to Oracle Autonomous AI Transaction Processing while this was being written, so a page title at the far end of a link may differ from the name in the sentence citing it.

The claim discipline set out in chapter 3 applies unchanged here: what Oracle documents carries a link at the point of use, what follows by engineering derivation is stated with the reasoning shown, and what was observed on a running instance is marked as a field observation. Part five, in particular, turns on that distinction.

Part V — Data Sources

A connection with no password, a controlled test with one variable, and a database in someone else’s cloud

31. What a connection actually is

A connection in this product is routinely treated as a host, a port and a credential. That description is wrong in a way that costs time, because it omits the four properties that determine whether the connection is safe, auditable and reproducible: which identity it presents, which transport it negotiates, which private path it takes, and which product surface may consume it.

Those four properties are independent axes, not a menu of six mutually exclusive choices, and reading them as a menu is the mistake this table exists to prevent. Connect Using selects the identity — Basic or Resource Principal. Encryption Type selects the transport — TLS or Mutual TLS. The private path is decided by the channel and by whether Data Gateway is in play. System connection is a usage flag for semantic-model tooling — it makes the saved connection available to data modellers — and it sits on top of any of the others.

A real connection is therefore a point in that space, and the combinations compose: Basic with TLS, Basic with mutual TLS, Resource Principal with TLS, Resource Principal with mutual TLS. Section 34 is the controlled test that moves exactly one axis while holding the other three.

Table 22 — The four axes a connection is defined on, and the control that matters for each

Two rules follow, and they are the ones a connection catalogue should enforce.

A saved connection is not an accepted connection. The wizard’s success message means the object persisted. The acceptance criterion is the reading of known data through a dataset, with a verifiable row count. Everything short of that is a pre-test.

The two private mechanisms are not exclusive. Oracle answers the question directly — “Can I use both a private access channel and Remote Data Gateway? Yes” (Top FAQs for Private Sources) — which matters for an estate that reaches some sources through the channel and others through an agent. The axis has three positions, not two.

The channel is never a field in the wizard. For private sources it acts implicitly, on the routing of the FQDN, exactly as Manage Connections to Data Sources describes. There is no dropdown that says “use the private channel”. If the name resolves through a registered zone, the channel carries it; if it does not, something else does. The absence of the field is why so many teams believe they are on the private path when they are not.

32. The resource-principal chain

Figure 19 — The resource-principal chain and the transport outcome. The identity path and the network path are identical for both branches; only the encryption type differs, and the mutual TLS branch fails at session begin.

The objective is a connection to a private Autonomous Database that stores no credential at all: the analytics instance is itself the principal. This is the most valuable single capability in a private deployment, because it removes the one artefact that every credential-rotation policy, every secrets-management review and every leaked-configuration incident revolves around.

The chain has six logical links, but only part of it is tenant-configurable. The controlled design establishes the caller, the IAM authorization gate, the private transport and the database identity mapping. The OAC Resource Principal connection form does not expose the managed connector’s token request, token-scope parameter, temporary key material or internal call sequence. Those details are therefore treated as an opaque managed-service boundary here rather than reconstructed as if they had been observed on the wire.

The database side has to be provisioned for it first: an Autonomous Database with a private endpoint, per Private Endpoints for Autonomous Database, with OCI IAM external authentication enabled. The six logical links are:

1. A dynamic group whose matching rule recognises the analytics instance by resource.id, per Writing Matching Rules to Define Dynamic Groups.
2. The tested IAM DB_CONNECT authorization, expressed directly as use database-connections and narrowed with target.database.id for the target-state design.
3. The OAC instance obtains and uses its resource-principal identity through the managed connector.
4. The connector performs the managed database-token authentication exchange; its internal request parameters are not a tenant configuration surface in OAC. What Oracle does document about the credential itself still applies: a database token requires a TCPS session and expires after one hour (Authenticating and Authorizing IAM Users).
5. The session traverses the private access channel to the Autonomous Database private endpoint over the selected TLS or Mutual TLS branch.
6. The authenticated resource principal resolves to the globally identified schema mapped to the OAC instance OCID, per Accessing the Database Using an Instance Principal or a Resource Principal.

This is deliberately a design chain, not a claim about undocumented OAC backend internals.

-- dynamic group: match the analytics instance by its OCID
resource.id = '<analytics-instance-ocid>'

-- the grant that carries DB_CONNECT
allow dynamic-group <domain>/<oac-dynamic-group> to use database-connections
  in compartment <database-compartment>

use autonomous-databases is not part of this and must not be added. It grants operations on the database resource; the token path needs DB_CONNECT, which database-connections carries. An earlier version of this article included it, and including it made the example broader than the design it was illustrating.

32.1 Two scopes, not one — and the second is the one that gets forgotten

This is the part that the policy alone does not tell you, and it is where a least-privilege design is actually won or lost.

The policy scope decides which databases the principal may be authorised against. Oracle states the three widths plainly: “Policies can allow IAM users to access Autonomous Database instances across the entire tenancy, in a compartment, or can limit access to a single Autonomous Database instance” (Create IAM Groups and Policies). The single-instance form uses a where clause on the target:

allow dynamic-group <domain>/<oac-dynamic-group> to use database-connections
  in compartment <database-compartment>
  where target.database.id = '<autonomous-database-ocid>'

The tested baseline stops at the direct grant above. The controlled tests, Support record, customer-delivered PoC/LLD and published Part One establish database-connections with target.database.id as the target-state authorization gate for this path. This article makes no inclusion or exclusion claim about autonomous-database-family. Public Oracle material on that aggregate is not internally consistent enough to replace the tested grant; the family relationship is therefore left as a documentation issue, not converted into either a broader policy or an opposite assertion.

The token scope is a second, independent control on the credential itself, and it uses a URN grammar rather than policy syntax. The same grammar appears on the CLI helper oci iam db-token get, on generateScopedAccessToken, and on the client-side iam.db.token.scope property:

urn:oracle:db::id::*                                    any database in scope
urn:oracle:db::id::<tenancy-ocid>                       one tenancy
urn:oracle:db::id::<compartment-ocid>                   one compartment
urn:oracle:db::id::<compartment-ocid>::<adb-ocid>       one specific database

The rule that binds the two: the token scope must be the same as, or more restrictive than, the scope the policy grants (Create a Database Tools Connection Using Token-Based Authentication). A token requested at a width the policy does not cover is refused; a token requested narrower than the policy is honoured at the narrower width.

That asymmetry is useful for clients that expose token scope. There, IAM policy is the authorization ceiling and the requested token scope can narrow one credential further.

The managed OAC Resource Principal connector is different. Its connection form does not expose iam.db.token.scope, a CLI --scope, temporary key material or a GenerateScopedAccessToken request. The tenant-controlled least-privilege boundary that this design can set unambiguously is therefore the IAM policy itself: use database-connections narrowed to the target Autonomous Database with target.database.id. This article does not claim that the tenant can force OAC's internally requested token to carry the single-database URN unless Oracle exposes or documents such a control.

32.2 The token does not replace the network

Even with a correct identity and a correct policy, the session still has to traverse the channel and reach the private endpoint. A routing failure produces an error that looks like an authorization failure, and the instinctive response — widen the policy — makes the environment less secure without making the connection work.

This is worth stating as a rule because it was tested directly. During troubleshooting a deliberately broad policy was applied, granting manage on the aggregate database family. The outcome did not change. That single negative result is more useful than a dozen successful ones: it strongly reduces the probability that a residual failure is a missing permission, and it removes "grant more manage" from the list of legitimate next steps. Steady state reverts to the single-database database-connections grant of section 32.1. No tenant-controlled OAC token-scope claim is made.

Build the chain as successive baselines, so that any failure is attributable to one variable:

Table 23 — Three successive baselines, and what each one does and does not prove

The second baseline is regularly confused with the third. They are different identity types with different mappings, and passing the second tells you nothing about the third.

33. The global schema, and the OCID that maps it

This is the step that gets under-documented and then blamed on something else.

The IAM_PRINCIPAL_OCID string in the global user definition does not contain the OCID of the dynamic group, nor of a human user, nor of the compartment. It contains the OCID of the analytics instance. That binding is what allows the token the instance presents to resolve to a database session.

-- on a database that has never had external authentication enabled
BEGIN
  DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(type => 'OCI_IAM');
END;
/

CREATE USER ANALYTICS_APP IDENTIFIED GLOBALLY AS
  'IAM_PRINCIPAL_OCID=<analytics-instance-ocid>';

GRANT CREATE SESSION, CONNECT, DWROLE TO ANALYTICS_APP;
ALTER USER ANALYTICS_APP QUOTA UNLIMITED ON DATA;

Do not add force => TRUE reflexively. Oracle states that the procedure should not be rerun when the provider is already enabled, and that "using the force parameter can break an existing external authentication configuration" (Use External Authentication with Database Tools). On a first enablement it changes nothing; on development, test or production after the first pass it is a destructive change wearing the syntax of an idempotent one. Check the current provider before running anything.

CREATE SESSION is the functionally essential privilege. CONNECT and DWROLE reflect a delivery-phase configuration and should be re-examined before production — a global schema that the analytics platform authenticates into is exactly the account where a broad role is least appropriate.

The explicit tablespace quota is not optional for a schema that writes. The RESOURCE role no longer confers unlimited tablespace, so a schema that creates tables or receives data-flow output needs an explicit quota; without it the first creation fails, the schema stays empty, and the consequence surfaces two layers away as described in section 35. A schema that only reads objects owned by others does not need one — but decide which of the two you are building, because section 37 argues that the analytics schema usually ends up being both.

33.1 The mapping actually used, and a public documentation conflict

The deployment used the exclusive global-schema mapping with the analytics instance OCID:

CREATE USER ANALYTICS_APP IDENTIFIED GLOBALLY AS
  'IAM_PRINCIPAL_OCID=<analytics-instance-ocid>';

That mapping is a closed project fact. With the same mapping in place, the Resource Principal connection over TLS established a session, discovered metadata and read objects as that schema. The value is the OCID of the analytics instance — not the dynamic group, not a human user and not the compartment.

Oracle public documentation has contained conflicting statements about exclusive versus shared mapping for instance/resource principals. That conflict is recorded as a documentation issue; it does not replace the controlled result above and it does not create a fallback requirement for this design. The target-state mapping remains the exclusive IAM_PRINCIPAL_OCID form that was actually validated.

It also cannot explain the Mutual TLS failure in section 34. The same exclusive mapping passes over TLS. A mapping rejected by the database would not selectively fail only when the encryption type changes. The mapping is therefore excluded as the explanation of ORA-25704.

33.2 Verify on the database side, in two independent steps

Creating the user is not finished until the database itself shows the expected identity and the expected grants. These are two different questions and they need two different queries.

-- 1. authentication: is this really a globally identified OCI_IAM user?
SELECT username, authentication_type, identity_provider_type
FROM   dba_users WHERE username = 'ANALYTICS_APP';

-- 2. privilege: what roles does it actually hold?
SELECT grantee, granted_role FROM dba_role_privs
WHERE  grantee = 'ANALYTICS_APP' ORDER BY granted_role;

-- 3. objects: does the schema own anything at all?
SELECT owner, table_name FROM all_tables
WHERE  owner = 'ANALYTICS_APP' ORDER BY table_name;

A session can authenticate perfectly and show no tables, because it owns none. Query three exists to separate those two facts before anyone starts editing policies. If query one returns nothing at all, the mapping form is the first thing to check — see section 33.1.

34. The controlled test: one variable

For this section, the controlled project record and the Oracle service cases are the authority. The OAC connection used Connect Using = Resource Principal against the same private Autonomous Database through the same Private Access Channel. The private database target was TCPS/1522 on both runs. The only variable moved in the final controlled test was the OAC Encryption Type: TLS versus Mutual TLS.

The history explains why this distinction matters. Earlier in the investigation, the Resource Principal path did not pass. During the case, Oracle corrected an ADB-side private-endpoint wallet/descriptor bug. After that Oracle-side correction, the TLS branch moved from failure to PASS. The Mutual TLS branch did not: it continued to fail on the same private path.

Table 24 — The controlled test: everything held constant except the encryption type

TLS — PASS. The connection saves, metadata is navigable, and the schema’s tables become visible once they exist. This is stronger than a connection-button success: it demonstrates session establishment, metadata discovery and object access in the context of the global schema. Resource Principal + TLS + private Autonomous Database through the PAC is the validated and adopted path.

Mutual TLS — FAIL. The same configuration with only Encryption Type switched from TLS to Mutual TLS returns ORA-25704 during OCISessionBegin:

ORA-25704: Current configuration does not use SSL_SERVER_DN_MATCH=TRUE. Token based authentication requires SSL_SERVER_DN_MATCH=TRUE with server authentication.

The generic interface message is not the useful evidence; the backend OCISessionBegin error is. More importantly, the status of this branch is now closed at the customer-classification level: the OAC team reproduced the private-path failure, Oracle Engineering validated the remaining Mutual TLS behaviour as a product bug, and Oracle Development teams are working toward mitigation. Oracle Support confirmed that there is no customer action item at this time.

34.1 The structural constraint of a managed path

The mTLS test was configured on the OAC connection itself by selecting Mutual TLS and supplying the Client Credentials wallet. The tenant can supply that wallet but cannot edit the sqlnet.ora, replace the tnsnames.ora, or override the descriptor that the managed analytics backend ultimately consumes.

That distinction became decisive during the case. The ADB-side wallet/descriptor was corrected, and the regenerated material contained SSL_SERVER_DN_MATCH=yes. ADB Support confirmed that yes is an enabled/true value for Oracle Net and that the wallet is not required to emit the literal TRUE. After the ADB-side correction, TLS passed while mTLS still failed. The generic yes-versus-TRUE syntax theory is therefore excluded by the project evidence.

The remaining private-path mTLS behaviour was independently reproduced by Oracle’s OAC team. Oracle Engineering has classified it as a product bug; Development teams are actively working toward mitigation, with no customer-actionable configuration change pending. The internal code-level mechanism remains Oracle’s implementation detail. The customer-side technical position does not: use the passing TLS branch and keep mTLS as a known defect until Oracle delivers a fix and the same controlled matrix passes.

35. What the PASS excludes — and what it does not

Figure 20 — The controlled test read as evidence: what the TLS pass proves, what the Mutual TLS failure isolates, and how the Oracle Engineering bug classification fits the observed boundary.

The correct inference from a passing TLS run is restrictive, not absolute. Writing it out as a table is the discipline that keeps a support conversation honest.

Table 25 — What the passing TLS branch excludes, and what Oracle Engineering has now classified

The classification is therefore not open anymore. Oracle Engineering has validated the remaining Resource Principal + Mutual TLS failure on the private OAC-to-Autonomous path as a product bug, and Oracle Development teams are working toward mitigation. The exact internal code-level root cause is an Oracle implementation detail; it is not required to classify the customer-facing result or to choose the production path.

This is the claim discipline of the whole article in one example. Say what was held constant, say what moved, say what the result excludes, and stop.

35.1 The empty-schema trap

After the first successful TLS save, the metadata browser showed mostly Oracle-maintained schemas. The initial hypothesis — that the application schema needed to be ORDS-enabled — was wrong. The schema simply owned no tables yet, because the tablespace quota of section 33 had not been granted and the first creations had failed.

Once objects existed and the quota was in place, the product listed them correctly. ORDS enables REST services and Database Actions; it is not a prerequisite for the connector’s SQL metadata discovery.

The general form of this trap is stated here as a field observation, not as documented behaviour: on the environments used for this work, the schema browser listed schemas that owned at least one visible object, and an empty schema with a perfect identity mapping did not appear at all. Its invisibility looks exactly like a permission problem. Whether the enumeration is object-based in every release is not something this article establishes; what it does establish is that an empty schema is the first thing to rule out, and that ORDS is not the remedy.

36. A database in another cloud

The PostgreSQL source is the practical demonstration of the cross-cloud path described in Part III: a resource that does not live in Oracle Cloud at all, reached privately behind a dynamic routing gateway.

36.1 Specify the firewall request completely, once

A first, generic request — “open 5432 from Oracle Cloud” — was insufficient and produced a round trip. The request that worked was a full specification:

Table 26 — The complete firewall request for a cross-cloud database path

Both egress addresses, in both directions. Authorising only one of the two can produce an intermittent failure that presents as a JDBC timeout and gets investigated as a performance problem — that is what happened here, and it is worth checking first. This single line has saved more time than any other item in the runbook.

36.2 The connection

The form asks for host, port, database, credentials and an SSL mode. Use the private FQDN, never an address. Use a read-only technical role — connect, usage, and select on the objects required — never a superuser. Give the connection a traceable name carrying owner, environment and change reference.

Two documented limitations shape the design, and both belong on the compatibility checklist rather than in the acceptance report. The PostgreSQL connector supports the private access channel and system connections, but:

• it does not support Server Name Indication for TLS,
• it does not support PostgreSQL on Neon,
• it is not available to Oracle Analytics Publisher — the connectivity table marks Publisher as unsupported, so pixel-perfect reporting cannot use this source at all, and
• it lists supported versions as 9.0+, 13, 14 and 15, which is worth checking against the partner platform’s actual release before the design is signed.

The first is the one that bites a private design. A TLS endpoint that selects its certificate by SNI — a shared load balancer, a managed proxy, several databases behind one address — will be handed a handshake with no server name, and will answer with the wrong certificate or refuse. This is not a tuning problem and there is no connector setting for it: verify the far side does not depend on SNI before adopting the connector, not during acceptance. Where it does, the endpoint has to be given a dedicated address and certificate, which is a change on the other cloud’s side and therefore a lead time.

An earlier draft of this article carried the SNI limitation as a field observation. It is documented, and it is stated here as documented.

The gate closes on a dataset with a known row count, a preview, and a recorded timestamp — not on the wizard’s confirmation.

37. Data flows, and where output can land

Four events must be kept separate, because collapsing them produces a false conclusion:

1. Connection to the source — PASS
2. Preview and dataset — PASS
3. Data flow transformation
4. Persistence of the output

Events 3 and 4 were tracked under a service request during the engagement, and the record contains the reference and the context but no concluded root cause. The rigorous statement is therefore: private reads from PostgreSQL pass; data flow end to end and the Save Data target are a historical investigation, to be retested on the current release. It would be wrong to write that PostgreSQL is not supported for data flows.

The design consequence is independent of that open item and worth stating on its own. A data flow’s Save Data step targets internal datasets and supported databases. Object storage is not a target. In a private deployment where the Autonomous Database is already on the private path, this makes the database the natural persistence target for data-flow output — which means the global schema of section 33 needs write privileges and a quota sized for output, not just read privileges sized for discovery.

Design the schema for both roles at the start. Retrofitting write access to a globally identified schema means re-opening the database-side change that everyone believed was finished.

Part VI — The Front Door

Two client paths, one incident nobody could route around, and a certificate the console accepted and the browser did not

38. Two paths, and why the client must take both correctly

Figure 21 — The two client paths. The identity domain is a public endpoint reached through the corporate proxy; the analytics instance is a private address reached over the VPN, with resolution provided by the tenant.

On a private instance the user’s browser has to accomplish two different things, over two different network paths, and the two are routinely conflated into one “can I reach the site?” question.

Table 27 — Two client paths, and the error each one produces when it is wrong

The observed failure mode was precise, and is offered as a field observation rather than a general pattern: the workstation is configured to send everything through the corporate proxy, including traffic destined for the private endpoint, or conversely to bypass the proxy for the identity domain that requires it. The first produces a broken TLS handshake against a private address the proxy cannot reach; the second produces ERR_SSL_PROTOCOL_ERROR against the identity provider.

The remedy is a split configuration, stated explicitly in the client-side runbook: the identity domain goes through the proxy; the private endpoint is reached directly over the VPN. Neither half is discoverable by the user, and neither half is the analytics service’s fault, which is why both belong in the delivery documentation rather than in a support queue.

A private endpoint has no public DNS record. Oracle does not create one, and About Private Endpoints states the consequence directly: the URL is only reachable from a browser if the client machine can resolve the name. That resolution is the tenant’s responsibility, on the tenant’s DNS, in the view the clients use. It is a delivery task with a lead time, and it is not visible in any Oracle console.

39. The 404 that came after a successful login

An incident is worth a chapter when the shape of the evidence, rather than the fix, is the transferable part. This is that incident.

39.1 The observation

After the identity provider authenticated the user, the browser followed two successful redirects and then received HTTP 404 on the application login path. The waterfall is the whole argument:

• Redirect one — to the identity provider — 302
• Redirect two — the callback returning to the application — 302
• The final application request — 404

Two facts follow immediately and they eliminate most of the usual suspects. The 404 arrives after authentication completes, so it is not a credential, a federation or a token problem. And the redirects succeeded, so it is not a channel timeout and not a network problem: it is an application path.

Cross-referencing status against initiator sharpened it further. The main application routes answered 302 while the specific login path answered 404. The breakage was punctual, not systemic — which is the difference between an outage and a defect, and it changes who is called.

39.2 What made the evidence usable

Three properties, and they are the reusable part:

Deterministic reproduction. The failure was reproduced on demand with browser developer tools, not observed intermittently. A support organisation can act on a deterministic reproduction and cannot act on a report.

Remote address captured. The request’s remote address was the private endpoint, which proves the return path was correct and removes the network team from the investigation in one line.

Reproduced in a private browsing session. Same remote address, same result — which excludes cache and residual session, the two hypotheses that otherwise consume a day.

Cookies and session data were redacted in both captures. This matters: an evidence pack that cannot be attached because it contains live session material is not an evidence pack.

39.3 The outcome, stated honestly

The incident was resolved through Oracle Support, and the internal root-cause analysis was not made available to the tenant. The behaviour was attributed to the service’s patch level at the time.

This article does not infer a root cause from that, and neither should a design document. What it does record is the method: authenticate first, then look at where in the sequence the failure lands; capture the remote address to prove the path; reproduce deterministically and in a clean session; redact before attaching. That method is what turned an unactionable “the login does not work” into a service request that closed.

The related client-side error, ERR_SSL_PROTOCOL_ERROR against the identity domain, was a separate finding with a separate cause — the proxy path of section 38 — and it is worth noting that the two were initially reported as one symptom. Separating them was the first useful act of the investigation.

40. A custom name, without a load balancer

The service publishes an Oracle-generated URL. Most organisations want a name they own, and the assumption that this requires a load balancer in front of the instance is both common and wrong.

The capability is built into the service and is described in Vanity URLs, with the material you must have ready listed in Prerequisites for a Vanity URL. A customer-managed load balancer is not required merely to terminate a custom hostname, which is the assumption that most often adds a component, a cost and a failure domain to the design for no reason.

The custom name is configured on the resource, in the cloud console — not in the authoring environment. The path is the instance’s Details page, Vanity URL, Configure, per Set a Custom Vanity URL and Configure a Vanity URL using the Console. The authoring environment subsequently uses the published name, but it is not where the hostname and certificate are bound.

Two consequences of that placement:

The operation falls under ANALYTICS_INSTANCE_MANAGE. It is a control-plane change on the resource, so it is excluded from any read-only profile and it appears in the audit trail as an instance modification, not as an application change.

Renewal is a distinct operation from configuration. Updating certificates for a vanity URL is its own console action and does not require recreating the DNS record. Runbooks that treat renewal as “do the configuration again” schedule unnecessary DNS work and unnecessary risk.

Three things are required and all three are the tenant’s:

1. A DNS record resolving the chosen FQDN to the private endpoint address, in the view the clients use.
2. A leaf certificate whose subject alternative name matches that FQDN, with key usage and extended key usage valid for a TLS server.
3. The complete chain to a trusted certification authority.

Self-signed certificates are not supported — but a private certification authority is explicitly allowed, which is the case this deployment is in: “Self-signed certificates aren’t supported. However, you can create your own root signing certificate and use that to sign a certificate that you generate yourself” (Top FAQs for Vanity URLs). Wildcard certificates are supported. The Oracle-generated URL remains available and should be kept as a tested fallback through configuration and every renewal.

Three limits from the same page belong in the design rather than in a discovery conversation. One vanity URL per instance. A single vanity URL definition may carry up to three fully qualified hostnames. And the feature can be exercised before any public DNS record exists, by adding the chosen name to /etc/hosts on one workstation pointed at the instance address — which turns certificate validation into something that can be done in the change window before the DNS request has landed.

40.1 One note on the domain

In the environment described here the certificate came from a private certification authority and the name used a .local top-level domain. It was accepted, and the failure that did occur was attributable to the certificate's extended key usage, not to the hostname.

.local is reserved for multicast DNS and is not a delegable public suffix, which is a general networking constraint rather than anything this product states. For production, choose a domain your organisation actually controls in public or private DNS — not because .local was observed to fail here, but because a name that cannot be delegated is a dependency on local resolution behaviour that nobody has agreed to support. Verify the current prerequisites page before committing to a naming scheme.

41. Certificates: what the console accepts is not what the browser accepts

Figure 22 — A custom name without a load balancer: DNS record, leaf certificate with a matching subject alternative name, and the chain to the trusted authority. All three are the tenant’s.

The first bundle uploaded was accepted by the console and rejected by the browser with ERR_SSL_KEY_USAGE_INCOMPATIBLE. The certificate was not valid for use as a TLS server.

A successful upload is not a validity proof. The console validates format and internal consistency; the browser validates purpose. They are different checks and they run on different sides of a change window.

The replacement, with a correct subject alternative name, correct key usage and extended key usage, and a correct chain, resolved it.

41.1 Validate before uploading

Four commands, run on the bundle, before it goes anywhere near the console:

# subject, issuer and validity window
openssl x509 -in leaf.cer -noout -subject -issuer -dates

# the three extensions that decide whether a browser will accept it
openssl x509 -in leaf.cer -noout -ext subjectAltName,keyUsage,extendedKeyUsage

# does the leaf actually chain to the CA you think it does?
openssl verify -CAfile chain.pem leaf.cer

# after configuration: what does the endpoint really present?
openssl s_client -connect <private-endpoint>:443 \
  -servername <vanity-fqdn> -showcerts

The fourth command is the acceptance test. It is the only one of the four that exercises the deployed configuration rather than the file on disk, and it is the one most often skipped because by then the browser has already loaded the page for the engineer who has the private CA in their trust store.

41.2 Assembling the fields

The configuration form takes the certificate, the private key and the CA chain as separate inputs, and the split is where a two-level private CA hierarchy causes trouble. Extract the leaf alone for the certificate field; put the issuing chain — the intermediate certificate or certificates, and the root where required — in the CA chain field. A two-level hierarchy is the simple case; an enterprise PKI with one or more intermediates puts all of them there, in order. A bundle pasted whole into the certificate field is a common and silent error.

41.3 Validation, rollback and hygiene

Table 28 — Validation, rollback and hygiene for a custom hostname and its certificate

The private key is never written into a document or an unprotected ticket. Distributing the trust store to the workstations is a desktop-management activity with its own lead time, and it belongs on the delivery plan rather than being discovered on cutover morning.

Part VII — Logging by Design

Five evidence levels, two of which require deliberate capture before the fault

42. Five levels, not one

Figure 23 — Five observability levels. Work requests and OCI Audit are automatic; detailed in-product query logging depends on LOGLEVEL, which is disabled by default, and the service logs must be enabled per category — both before the fault they are meant to explain.

Every incident described in this article — the login 404, the cross-cloud timeout, ORA-25704 — was diagnosed by correlating sources that live in different places and are enabled by different people. None of them was diagnosed from a single log.

Get Alessandro Moccia’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

That is the argument for treating observability as an architectural decision made at provisioning rather than an operational habit acquired later. There are five levels. They are not layers of the same thing; they answer different questions and they are governed by different authorization models.

Table 29 — The five observability levels, and which of them you have to enable

The distinction between 3 and 4 is the one most often collapsed, and the two are complementary rather than redundant: service logs observe what users do inside the application; OCI Audit records operations performed on the resource. A role change inside the product appears in the first and not the second. A channel reconfiguration appears in the second and not the first.

Level 5 is the one that resolved ORA-25704. Oracle Support located the error inside OCISessionBegin while the tenant could see only a generic interface message. Treat it as evidence obtained through a service request, never as a source you can query.

The rule that makes the rest of this part matter. A source that did not capture the event cannot be reconstructed afterwards. Levels 2 and 4 are automatic and level 5 is Oracle’s. Two are not. Level 1’s Sessions and Query Logs page is always present, but the query detail behind it depends on LOGLEVEL, which is 0 — disabled — by default; the page existing is not the same as the SQL being captured. And level 3's service logs must be enabled per category. Configure both on day zero, before the first user signs in, not after the first incident.

43. Enabling the two service logs

The service publishes audit and diagnostic logs through OCI Logging, as described in Audit and Diagnostic Logs for Oracle Analytics Cloud. Enabling service logs and creating the required log group is governed by manage log-groups (LOG_GROUP_CREATE); reading the resulting events is governed separately by read log-content (LOG_CONTENT_READ). A read-only log consumer therefore does not need the delivery permission, and the delivery permission must not be described as manage analytics-instances.

The sequence, per Access Audit and Diagnostic Logs Using the Console:

1. Observability & Management → Logging → Log Groups. Select the compartment and create the group.
2. Inside the group, Logs → Enable service log.
3. Resource compartment: the one containing the instance. Service: Analytics Cloud. Resource: the instance.
4. Log category: Audit Logs or Diagnostic Logs.
5. Log name and, under advanced options, retention.
6. Enable. The state moves from Creating to Active, and from that moment events are searchable.

Three things about that sequence are worth more than the sequence itself.

They are two distinct log objects. Choosing a category creates one log. If both are wanted, the procedure runs twice inside the same group. An environment with only Audit Logs enabled has no source-query diagnostics, and the gap is invisible until it is needed.

The default retention is one month, and it is configurable. OCI Logging allows the retention period to be changed in thirty-day increments up to one hundred and eighty days. Two asymmetries decide how that is used. Shortening it takes effect immediately: events older than the new period stop being available as soon as the change is applied. Lengthening it is not retroactive: events that have already aged out do not come back. For conservation beyond one hundred and eighty days, or for delivery to a security information and event management platform, export is the mechanism — decide the target retention before the first month elapses, not after.

Enabling is a manage operation and reading is not. These are two different profiles and they should be two different groups.

-- reading logs that already exist: the observation profile
ALLOW GROUP <domain>/<engineering-group> TO READ log-groups
  IN COMPARTMENT <log-compartment>

ALLOW GROUP <domain>/<engineering-group> TO READ log-content
  IN COMPARTMENT <log-compartment>

-- enabling the service logs: the delivery profile
ALLOW GROUP <domain>/<delivery-group> TO MANAGE log-groups
  IN COMPARTMENT <log-compartment>

manage log-content is not part of this and should not be requested. Oracle documents the pair precisely on Monitor Usage and Diagnostic Logs: enabling service logs and creating log groups is manage on log-groups, carrying LOG_GROUP_CREATE; reading the events is read on log-content, carrying LOG_CONTENT_READ. The log-groups resource type covers log groups and the log objects inside them, which is why one verb on one resource type is enough to create the group and enable both categories. Adding manage log-content widens the grant without enabling anything the delivery profile needs.

Before requesting either, check what the group already holds. A monitoring group with tenancy-wide read metrics and read alarms and no where clause already covers the analytics namespace and needs nothing added. A group whose grant is conditioned on target.metrics.namespace needs oci_analytics added to the condition. A compartment-scoped grant needs the new compartment. Three cases, three different answers, and asking for the wrong one costs a review cycle.

43.1 What each log actually contains

Audit logs record actions users initiate in the application: catalogue updates, exports, changes to security and application roles, snapshot operations, service-setting changes. This is the governance source for Part IV. A change to an application role, or an export of data from a workbook, produces an event with who, what and when — and it is the tenant-visible audit source for such a change, because role edits generate no work request.

Diagnostic logs expose the detail of queries against data sources: response times, the SQL issued, the errors returned by the source platform. This is the natural starting point for connection and performance analysis, and the place to look before involving the network team.

43.2 Client addresses are off by default

Capturing the client IP in service logs requires the Enterprise setting Include Client IP Addresses in Service Logs to be switched on explicitly. The default is off.

Enabling it makes workstation identification direct, so it needs a privacy assessment and a tracked change — not a quiet toggle. It is also the setting most likely to be missed and then wanted retrospectively, which is precisely the situation the rule at the end of section 42 describes.

44. In-product logs, and the level nobody enables

From the product home: Navigator → Console → Session and Query Logs, exposing sessions and the cursor cache for analyses and dashboards.

By default the query detail is not captured. LOGLEVEL is 0, which means logging disabled, so the page can be open and show sessions while the logical and physical SQL that an investigation needs was never written. This is the distinction that costs an afternoon: the surface is always available, the capture is not. For a targeted investigation:

SET VARIABLE LOGLEVEL = 3, DISABLE_CACHE_HIT = 1;

Two clarifications that prevent a category error. This level is not OCI Audit, and it does not coincide with the service logs published in OCI Logging — it is the BI engine’s own record, showing logical SQL, the physical SQL it generated, and the time each took.

And it is governed by application roles, not IAM. An engineer with manage on the instance in the cloud console may have no access to it whatsoever, while a user with the right application role has full access without holding a single IAM policy. This is Part IV's two-plane split appearing in the observability model, and it is why the logging section of a hand-over checklist has to be written twice.

DISABLE_CACHE_HIT = 1 matters more than it looks. Without it, a repeated test may be answered from the cursor cache, produce no physical SQL, and lead an investigation to conclude that the source was never queried — which is true, and misleading.

45. Which level answers which symptom

This is the attribution table. Its purpose is to stop the reflex of opening whichever log is most familiar.

Table 30 — Symptom to source: which level to open first, and what to correlate it with

The fourth row carries the most operational weight. A private-path timeout is investigated in three places at once, and the single most common cause is that one of the two egress addresses was authorised and the other was not — which produces a failure that looks intermittent and therefore looks like performance.

45.1 A field observation about diagnostic logs

During troubleshooting, diagnostic logs relating to the private path came back empty, and Oracle Support had to be involved for backend visibility.

This is evidence from a specific engagement and it must not be generalised. It is not a public rule that every instance needs a service request to enable normal audit and diagnostic logs — those are enabled by the tenant, from OCI Logging, by the procedure in section 43. The service request concerned the Oracle-managed backend layer, which is level 5.

Runbooks must keep the three categories visibly distinct — tenant logs, in-product logs, Oracle backend logs — because conflating them produces either a service request that should have been a console operation, or a console operation attempted where only a service request will do.

46. Correlation, and the evidence pack

Correlation is a time problem before it is a tooling problem. Use UTC, or declare the offset explicitly. A test recorded without a timestamp forces the support organisation to search wide windows and makes it easy to confuse retries, cache hits and separate sessions with one another.

Three identifiers tie the layers together, and all three should be captured as a matter of routine rather than retrieved under pressure: the request ID, the session ID, and the ECID. The ECID is the one that crosses from the interface into the query engine and on into the backend, and it is the identifier that made the ORA-25704 evidence usable.

Table 31 — Correlation cases, search keys, and the minimum evidence to keep

The minimum pack to attach to a service request: UTC timestamp, user or principal, address where available, category, operation, request ID, session ID, ECID, connection name, encryption type, the complete message, screenshots, and the outcome of the negative test that accompanies the case.

That last item is the one that distinguishes a case that moves from a case that sits. A report that something fails invites a request for more information. A report that A fails and B, differing in exactly one variable, succeeds, is an experiment — and it is answered.

47. Metrics and alarms — the plane that is not a log

Every level in section 42 answers the question what happened. Metrics answer a different one — how much, and is it getting worse — and they are another automatically available source: unlike detailed query logging and the service logs, they require no enabling step at all.

Oracle Analytics Cloud publishes native metrics into OCI Monitoring automatically. There is no operation comparable to creating a Log object; the namespace is populated from the moment the instance is active. Oracle documents the definitions in Metrics for Oracle Analytics Cloud and the selection workflow in Access Metrics Using Metrics Explorer.

text

Namespace:  oci_analytics
Dimension:  resourceName

Use resourceName in every query and every alarm. A tenancy with development, test and production instances in the same compartment tree will otherwise aggregate three workloads into one line, and the alarm that fires will not say which environment fired it.

47.1 The two metrics that matter, and what they are not

PercentQueryCapacityUsed is the percentage of query capacity in use. It is not physical CPU utilisation, and reading it as CPU is the error that turns a modelling problem into a purchase order. A persistently high value is consistent with high concurrency, expensive queries, an inefficient semantic model, poor cache effectiveness, or genuine under-sizing — five different causes with five different remedies, only one of which is scaling.

Before acting on it, correlate with the Session and Query Logs of section 44: the physical SQL and its timing tell you whether the capacity is being consumed by work the database should have done. Part II section 6 makes the same point from the sizing side, and this metric is where it becomes measurable.

DataSourceConnectionErrors counts connection errors for data sources used by the semantic model. Treat it as a symptom counter, not a classifier: it reports that connections failed, and it does not attribute the failure to DNS, routing, a security rule, a listener or a credential. The classification belongs to the diagnostic logs of chapter 44. Its value is that it moves off zero at all, on a path where zero is the expected reading.

Its coverage is not universal, and Oracle says where the boundary is rather than leaving it to inference: “Self-service connection errors aren’t captured at this time” (Metrics for Oracle Analytics Cloud). A workbook or dataset connecting directly, outside the semantic model, produces no counter at all. Diagnostic logs and the in-product query logs therefore remain necessary; the metric tells you that something on the modelled data path degraded, not which connection, and it is silent on everything self-service.

47.2 Reading metrics is a different grant from reading logs

One surface is not covered by either grant. The Metrics tab on the instance details page is visible only to “an administrator with manage access” (Access Metrics Using the Console). The observation profile reads the same metrics through Metrics Explorer and never sees that tab — the same shape as the channel’s egress addresses in chapter 12, and worth stating in the runbook so nobody reports it as a fault.

ALLOW GROUP <domain>/<monitoring-group> TO READ metrics
  IN COMPARTMENT <analytics-compartment>

ALLOW GROUP <domain>/<monitoring-group> TO READ alarms
  IN COMPARTMENT <analytics-compartment>

Before requesting either, resolve the three cases set out in section 43: a tenancy-wide grant with no where clause already covers the namespace; a grant conditioned on target.metrics.namespace needs oci_analytics adding to the allowed set; a compartment-scoped grant needs the new compartment. Policies inherit down the tree, so a grant on a parent compartment may already cover an analytics compartment created beneath it. Check the effective policy before asking for a duplicate.

47.3 Building the alarm

Oracle documents the mechanics in Creating an Alarm and the resource filter in Selecting a Resource for an Alarm Query. The sequence that produces an alarm somebody will actually act on:

1. Choose or create the notification topic first — an alarm with no subscriber is a dashboard widget.
2. Create the alarm in the compartment holding the instance.
3. Select the oci_analytics namespace and the metric.
4. Filter by resourceName.
5. Choose the interval and the statistic. Oracle documents the cadence for this service directly — “the metric count occurs every five minutes” (Access Metrics Using the Console) — and the alarm interval may never be shorter than the emission frequency (Monitoring Query Language Reference). Five minutes is therefore the floor, not a preference. For the baseline below, mean() for query-capacity percentage and sum() for connection-error counts are engineering choices to validate against the workload, not Oracle-prescribed statistics.
6. Set operator, threshold and pending duration.
7. Assign a severity that maps to your escalation policy, not to how the metric feels.
8. Associate the topic.
9. Test the alarm semantics, not only the colour in the Console: OK_TO_FIRING, the normal FIRING_TO_OK, and the RESET path when a metric stream that caused firing disappears for the internal reset period. If repeat notifications are configured, verify REPEAT as well. REPEAT is not a state transition; RESET returns the alarm to OK and is a reason to check the health of the emitting resource.

47.4 A starting baseline, and what it is not

Table 32 — An alarm baseline to tune — not an Oracle recommendation

These are an engineering baseline, not a recommendation. Where Oracle’s material offers an illustrative figure it is exactly that — an illustration, on a workload that is not yours. Collect a fortnight of data in development and test, look at the distribution, then set production values. A threshold copied from an article — including this one — is a guess wearing a number.

The connection-error row deserves the same treatment in reverse. On an environment with a clean private path the expected background rate is zero, and > 0 is the correct warning. On an environment with a flaky partner interconnect it is not, and setting it there produces an alarm that fires every day and is therefore no longer an alarm.

Part VIII — Continuity and Delivery

An export is a copy, not a proof — and a known failure left in the matrix is worth more than a clean one

48. Snapshots: the boundary of what they protect

Oracle separates the resilience of the service from the tenant’s responsibility for content. The backup of analytics content belongs to the tenant, and the mechanism is Snapshots.

A snapshot can carry the catalogue, reports, dashboards, workbooks, datasets, data flows, the semantic model, security roles and service settings. Oracle currently states that you can keep up to 40 user snapshots online and export as many as required to offline storage (Snapshots).

The same Oracle page separately states that the service automatically takes an internal snapshot when someone publishes semantic-model changes, keeps the 5 most recent, and applies a minimum interval of one hour between those automatically generated snapshots. The documentation cited here does not state a capacity relationship between the 40-user-snapshot limit and the five internal semantic-model snapshots, so this article does not infer one. The one-hour statement is recorded only for the automatically generated internal snapshots; it is not extended to a manual pre-change snapshot.

The boundary. Snapshots protect the content and the supported configuration of the analytics service. They do not protect the data in the source databases. After a restore, verify the catalogue, the semantic model, direct and indirect role membership, datasets, data flows, connections and settings; credentials and external systems may need separate action.

Take snapshots at meaningful checkpoints — in practice, before every invasive change to the catalogue, the semantic model or a security mapping — and at a frequency matched to the rate of change. Part IV gives the sharpest instance of this rule: adding one predefined application role to another is permanent, and restoring a snapshot taken beforehand is the only rollback. Record the snapshot identifier in the change ticket, not just the fact that one was taken.

RPO and RTO are not declared in advance. They are derived from frequency, retention, size and the outcome of a restore test. A recovery objective asserted in a design document and never measured is a number, not an objective.

Table 33 — The content backup plan, by artefact

The fourth row carries a trap from Part IV. A membership export that lists only direct assignments will look complete and will omit everything arriving through the role graph. Export both, or the restore validation is checking the wrong thing.

49. Automating the export, without a stored credential

For REST automation to a private object-storage bucket, Oracle recommends the instance’s resource principal (REST API prerequisites). This is the same mechanism as Part V, applied to a different target, and it removes the stored credential from the backup pipeline — which is exactly where a stored credential is most dangerous, because a backup job is long-lived, unattended and broadly privileged.

The policy must be scoped tightly on three axes:

ALLOW ANY-USER TO MANAGE objects IN COMPARTMENT <backup-compartment>
WHERE ALL {
  request.principal.type = 'analyticsinstance',
  request.principal.id   = '<analytics-instance-ocid>',
  target.bucket.name     = '<snapshot-bucket>'
}

ANY-USER with a full WHERE ALL clause is the correct construction here and it looks alarming to a reviewer who reads the first two words. Include the reasoning in the change request: the principal type, the specific instance OCID and the specific bucket name together form a scope narrower than a group grant, because the group grant would extend to every member of the group and this extends to exactly one resource.

One consequence to state explicitly in the design. Every feature of the analytics service that uses object storage through that resource principal shares this access. The scope is per-instance, not per-feature. Narrow it by bucket and, where the object model allows, by prefix.

The control is not complete without a negative test: an attempt against a bucket outside the scope, which must be denied, and whose denial must appear in OCI Audit. A policy that has only ever been observed to permit has not been tested.

50. The restore drill

An export that has never been restored is a copy, not a proof of restorability.

The drill runs in a controlled environment and validates, in this order: roles, connections, catalogue, semantic model, datasets and settings. Each of those can restore in a way that looks successful and is not.

Table 34 — Restore drill checks, and the failure mode each one catches

Not everything in the Console is inside a snapshot, and the boundary is a choice made at capture time. Oracle includes application roles, and treats Configuration and Settings as an option rather than a default; some configuration travels and system settings do not; credentials are likewise optional, and a snapshot taken without them restores content that has to be re-credentialled before it works. Record on the change ticket which options were selected, because a restore drill that assumes the maximum will pass in rehearsal and fail in the incident.

The semantic-model row deserves its own sentence, because Part IV establishes that the model holds a copy of the security policy store. A restored model can therefore present a security configuration that is internally consistent and no longer matches the identity domain around it. Validating it means running queries as a restricted principal, not reading the model in the administration tool.

51. Runbooks

Every change begins with a photograph of the current state and a written rollback, produced before execution. Control-plane operations generate traceable work requests; application-plane changes do not become analytics-instance work requests and therefore need their own evidence and rollback method. Use a snapshot when the affected content/configuration is snapshot-covered, and require a pre-change snapshot for the specific advanced operation that adds one predefined application role to another, because Oracle documents snapshot restore as the only rollback for that operation. Ordinary membership edits must not be described as irreversible by association.

Table 35 — Runbooks: pre-check, execution, post-check and rollback

Two entries encode findings from earlier parts. The channel row lists Enterprise edition as a pre-check because the operation is invisible without it (Part II). The roles row scopes the snapshot requirement to the advanced predefined-role-composition change (and other snapshot-covered changes); ordinary user/group/application-role membership edits are not given the same one-way semantics.

52. Acceptance gates, and the value of a known failure

The regression matrix is the artefact that survives the delivery team. It states what must be true, and — this is the part that gets removed by well-meaning reviewers — what is known not to be true.

Table 36 — The regression matrix, including the known failure kept as an expected result

The Engineering-validated mTLS bug stays in the regression matrix as an expected failure until Oracle delivers a mitigation/fix and the same controlled test passes. Removing it would hide the known product defect; treating it as a new customer fault would duplicate an Oracle Development investigation that is already in progress.

R-13 is the entry most often absent and the one an auditor will ask for. A least-privilege model that has only ever been observed to permit has not been demonstrated. The negative test — attempt a manage operation as the read-only profile, confirm the denial, confirm the denial appears in the audit trail — is what turns a policy design into a control.

52.1 The delivery position

The engineering decision recorded at the end of this work is worth restating in full, because it is the shape a defensible position takes when a branch is genuinely open:

Adopt Resource Principal with TLS as the validated path on the private endpoint. Record Resource Principal with Mutual TLS as an Oracle Engineering-validated product bug under active Development mitigation, with no customer action pending. Do not expose the database publicly to obtain a passing result. Do not accept an action plan that requires overriding a file the managed connector does not expose.

Each clause does work. The first states the delivered path. The second records the Oracle Engineering classification and ownership of the failing branch. The third refuses a workaround that would satisfy a test by violating the private-endpoint requirement. The fourth rejects a customer action that the managed connector does not expose and that Oracle Support has confirmed is not pending.

52.2 What “done” means here

Table 37 — Delivery state: closed, open, and defined but not yet operated

Three states, deliberately: closed, open, and defined but not yet operated. The third is the honest category for work that has been designed and specified but not yet run in anger, and it is the one that a delivery report usually converts into “complete” and shouldn’t.

Appendices

Copy-ready material, verification commands, and the reference index

A. Policy statements

Every statement uses placeholders. Substitute the identity domain, group and compartment names before use, and check where the environment’s compartment sits in the tree — policies inherit downwards, so a grant on a parent may already cover it.

A.1 Delivery — provisioning and configuration

ALLOW GROUP <domain>/<delivery-group> TO MANAGE analytics-instances
  IN COMPARTMENT <analytics-compartment>

ALLOW GROUP <domain>/<delivery-group> TO READ analytics-instance-work-requests
  IN COMPARTMENT <analytics-compartment>

-- required in the compartment where the NETWORK lives, not the instance
ALLOW GROUP <domain>/<delivery-group> TO MANAGE virtual-network-family
  IN COMPARTMENT <network-compartment>

ALLOW GROUP <domain>/<delivery-group> TO READ compartments IN TENANCY

A.2 Engineering — observation only

ALLOW GROUP <domain>/<engineering-group> TO READ analytics-instances
  IN COMPARTMENT <analytics-compartment>

ALLOW GROUP <domain>/<engineering-group> TO READ analytics-instance-work-requests
  IN COMPARTMENT <analytics-compartment>

ALLOW GROUP <domain>/<engineering-group> TO READ log-groups
  IN COMPARTMENT <log-compartment>

ALLOW GROUP <domain>/<engineering-group> TO READ log-content
  IN COMPARTMENT <log-compartment>

Do not add use: it carries start and stop. This profile cannot read the channel's egress addresses — that is manage — so publish them in the inventory.

A.3 Service logging — enabling

ALLOW GROUP <domain>/<delivery-group> TO MANAGE log-groups
  IN COMPARTMENT <log-compartment>

log-groups covers the log objects as well as the groups, so this one statement creates the group and enables both log categories. Do not add manage log-content: reading events is read log-content, and the manage verb on that type enables nothing the delivery profile needs.

A.4 Monitoring and alarms

ALLOW GROUP <domain>/<monitoring-group> TO READ metrics
  IN COMPARTMENT <analytics-compartment>

ALLOW GROUP <domain>/<monitoring-group> TO READ alarms
  IN COMPARTMENT <analytics-compartment>

Namespace oci_analytics, dimension resourceName. Filter every alarm query by resourceName, or environments sharing a compartment tree aggregate into one series.

Three cases before requesting anything: a tenancy-wide grant with no where clause already covers the analytics namespace and needs nothing; a compartment-scoped grant needs the new compartment; a grant conditioned on target.metrics.namespace needs oci_analytics added.

A.5 Configuring the private access channel

The channel needs network permissions that span two compartments: it reads the network where the network lives, and attaches VNICs and consumes private IPs where the instance lives.

ALLOW GROUP <domain>/<delivery-group> TO READ virtual-network-family
  IN COMPARTMENT <network-compartment>

ALLOW GROUP <domain>/<delivery-group> TO USE subnets
  IN COMPARTMENT <network-compartment>

ALLOW GROUP <domain>/<delivery-group> TO MANAGE vnics
  IN COMPARTMENT <analytics-compartment>

ALLOW GROUP <domain>/<delivery-group> TO USE private-ips
  IN COMPARTMENT <analytics-compartment>

-- only if network security groups are used on the channel
ALLOW GROUP <domain>/<delivery-group> TO USE network-security-groups
  IN COMPARTMENT <network-compartment>

-- only if a SCAN host and port is registered on the channel
ALLOW GROUP <domain>/<delivery-group> TO READ work-requests
  IN COMPARTMENT <analytics-compartment>

Note the resource type on that last statement. It is the generic work-requests, not analytics-instance-work-requests, and Oracle states it explicitly: "If you plan to enable access to a data source with SCAN host and port details, ensure that you ... belongs to a group that is granted the required policy to access work requests" (Prerequisites for a Private Access Channel).

This does not contradict chapter 20.2, which says the generic type does not cover reading the analytics work requests — that remains true, and those live on analytics-instance-work-requests. The two statements are about two different things, and an estate that registers SCAN hosts needs both.

A.6 Resource principal to a private database

-- dynamic group matching rule
resource.id = '<analytics-instance-ocid>'

-- the grant that carries DB_CONNECT
ALLOW DYNAMIC-GROUP <domain>/<oac-dynamic-group> TO USE database-connections
  IN COMPARTMENT <database-compartment>

-- least-privilege form: one database only
ALLOW DYNAMIC-GROUP <domain>/<oac-dynamic-group> TO USE database-connections
  IN COMPARTMENT <database-compartment>
  WHERE target.database.id = '<autonomous-database-ocid>'

The tested target-state path uses database-connections / DB_CONNECT and narrows the grant to one database with target.database.id. use autonomous-databases is not part of that tested authentication path and must not be added merely to make it work. This appendix makes no inclusion or exclusion claim about autonomous-database-family; any unresolved aggregate- family relationship remains a documentation issue and is not used to replace or widen the direct tested grant.

For clients that expose database-token scope, the credential can also carry a scope URN, which must be the same as or narrower than the policy:

urn:oracle:db::id::*                                any database in scope
urn:oracle:db::id::<tenancy-ocid>                   one tenancy
urn:oracle:db::id::<compartment-ocid>               one compartment
urn:oracle:db::id::<compartment-ocid>::<adb-ocid>   one specific database

Use the fourth form when the client actually exposes token scope. For the managed OAC Resource Principal connector, no token-scope control is exposed to the tenant in the connection form; the enforceable tenant-side least- privilege boundary is therefore the database-connections policy narrowed with target.database.id. Do not claim a tenant-controlled single-database URN for OAC unless Oracle exposes or documents that control.

A.7 Resource principal to a snapshot bucket

ALLOW ANY-USER TO MANAGE objects IN COMPARTMENT <backup-compartment>
WHERE ALL {
  request.principal.type = 'analyticsinstance',
  request.principal.id   = '<analytics-instance-ocid>',
  target.bucket.name     = '<snapshot-bucket>'
}

A.8 Compartment quotas

set  analytics quota ee-ocpu-count to 10 in compartment <analytics-compartment>
zero analytics quota ee-ocpu-count       in compartment <sandbox-compartment>

B. Verification commands

B.1 The database side of a global schema

sql

SELECT username, authentication_type, identity_provider_type
FROM   dba_users WHERE username = '<global-schema>';

SELECT grantee, granted_role FROM dba_role_privs
WHERE  grantee = '<global-schema>' ORDER BY granted_role;

SELECT owner, table_name FROM all_tables
WHERE  owner = '<global-schema>' ORDER BY table_name;

B.2 Network, from a temporary host in the channel’s subnet

bash

# 5 — name resolution. Run this FIRST.
nslookup <source-fqdn>

# 6 - socket. Only meaningful once 5 passes.
nc -zv <source-fqdn> <port>

A failure at 5 is a resolver, a forwarding rule or an unregistered zone. A failure at 6 with 5 passing is a route, a security rule or a listener. Both passing, with the product still failing, means credentials, transport or authorization. Delete the host afterwards.

B.3 Certificate material

bash

openssl x509 -in leaf.cer -noout -subject -issuer -dates
openssl x509 -in leaf.cer -noout -ext subjectAltName,keyUsage,extendedKeyUsage
openssl verify -CAfile chain.pem leaf.cer
openssl s_client -connect <private-endpoint>:443 \
  -servername <vanity-fqdn> -showcerts

B.4 Metrics and alarms

text

Namespace:  oci_analytics
Dimension:  resourceName

PercentQueryCapacityUsed     percentage of QUERY capacity - not CPU
DataSourceConnectionErrors   semantic-model data-source connection errors

Baseline to tune, never to adopt as given: an interval of at least five minutes, because that is the documented emission cadence; sustained ≈ 80% warning and ≈ 90% critical on query capacity, with a pending duration long enough to suppress transient peaks; > 0 on connection errors where the private path is expected to be clean. Validate OK_TO_FIRING, normal FIRING_TO_OK, RESET, and REPEAT when repeat notifications are enabled.

B.5 In-product query logging

sql

SET VARIABLE LOGLEVEL = 3, DISABLE_CACHE_HIT = 1;

B.6 Catalogue permissions

Catalog Manager connects to https://<host>/analytics-ws — append analytics-ws, exclude /ui. ACL letters: R read · X execute · L run report · S schedule report · V view output · F full control · N denied.

C. Ten decisions that are fixed, inherited, or expensive to revisit

Table 38 — Ten decisions that are fixed, inherited, or expensive to revisit

The edition used to be on this list and is not. Oracle documents a feature-set change on the instance’s Actions menu; chapter 5.2 shows where two Oracle pages disagree and how it resolves.

Items 1 to 7 are lifecycle or subscription constraints, fixed at creation or by the subscription. Item 8 is a one-way product-plane change with no work request. Items 9 and 10 are neither — they are inherited or revisitable configuration whose change requires coordinated revalidation, which is why they are missed rather than why they are impossible.

D. Reference index

Grouped by the part that uses them. Every link also appears in context, beside the claim it supports.

Foundations Administering Oracle Analytics Cloud on OCI (Gen 2) · Configuring Oracle Analytics Cloud · Create a Service using the Console · About Scaling · Service Quotas · View or Update a Service using the Console · Top FAQs for Administration · Do You Need a Public or Private Endpoint? · View the Dataset Storage Limit

Network About Private Endpoints · Create Oracle Analytics Cloud with a Private Endpoint · Top FAQs for Public or Private Endpoint Security · About Private Access Channels · Prerequisites for a Private Access Channel · Configure a Private Access Channel using the Console · About Private Sources · Top FAQs for Private Sources · Change the VCN or Subnet Used to Access a Private Endpoint · Manage Ingress and Egress Access Rules for a Private Analytics Cloud Instance · Troubleshoot Private Access Channel Connectivity · Troubleshoot Connectivity Issues Using Network Path Analyzer · Prerequisites for Network Security Groups · OAC Deployment Network Scenarios — Oracle A-Team

Identity and authorization About Permissions to Manage Oracle Analytics Cloud Instances · Managing Permissions in Oracle Analytics Cloud · Writing Matching Rules to Define Dynamic Groups · Predefined Application Roles · Assign Application Roles to Users · Add Your Own Application Roles · Grant or Revoke Permissions to Application Roles · Add One Predefined Application Role to Another (Advanced) · Download Membership Data · Why Is the Administrator Application Role Important? · Remove Users from an Oracle Cloud Service Application · Assign Access Permissions · Reporting on Catalog Object ACLs · Manage Presentation Services Privileges Using Application Roles · Set Semantic Model Privileges for an Application Role

Data sources Manage Connections to Data Sources · Resource Principal in Autonomous Database · Accessing the Database Using an Instance or Resource Principal · IAM Authentication on Autonomous Database · PostgreSQL connector · ORA-25704 · Private Endpoints for Autonomous Database · Authenticating and Authorizing IAM Users for Oracle Database Cloud Services

Front door Vanity URLs · Prerequisites for a Vanity URL · Set a Custom Vanity URL · Configure a Vanity URL using the Console · Update Certificates for a Vanity URL

Logging and continuity OCI Logging · OCI Audit · Audit and Diagnostic Logs for Oracle Analytics Cloud · Access Audit and Diagnostic Logs Using the Console · Monitor Usage and Diagnostic Logs · Include Client IP Addresses in Service Logs · VCN Flow Logs · Snapshots · Top FAQs for Backup and Restore · REST API prerequisites · Metrics for Oracle Analytics Cloud · Access Metrics Using Metrics Explorer · Creating an Alarm · Selecting a Resource for an Alarm Query

All environment-specific identifiers — region, tenancy, compartment, instance, hostname, address, resource identifier, service-request number, organisation and cloud-provider brand — have been removed. The pattern, the sequence and the constraints are what remain.