GoldenGate Admin Client: Web UI and REST API Access

Oracle GoldenGate Access Surfaces

Admin Client, Web UI, and REST API Three ways into the same Microservices control plane, each with different strengths, risks, and operational consequences.

Oracle GoldenGate Microservices does not force one operating style. A browser session, the Admin Client shell, and direct REST calls can all manage the same deployment, but they do not behave the same under pressure. The important distinction is not which one is newer or friendlier. It is where each entry point lands, how it authenticates, what scope it actually controls, and how repeatable it is when you need to verify, automate, or recover service access quickly.

Table of Contents

Section 01

Topic boundary and the core model you should not blur

GoldenGate Microservices introduced a control plane made of named services with embedded web applications and versioned REST interfaces. Admin Client joined that model as a shell that talks to the services instead of bypassing them. That matters because the real question is not whether you prefer command line or browser. The real question is which service you are entering, at what scope, with which identity, and for what kind of work.

Durable concept

Older GoldenGate training material described these components as Administration Server, Distribution Server, Receiver Server, and Performance Metrics Server. Current Oracle documentation uses the service terminology. The operational idea is unchanged: the deployment is administered through service endpoints, not through the classic single-process control surface.

Service Manager

Host-level manager for one or more deployments on the same server. It is the landing surface for deployment inventory, lifecycle actions, and console launch.

Administration Service

The day-to-day process administration surface for Extract and Replicat, checkpoints, and local trail management inside a deployment.

Other deployment services

Distribution, Receiver, and Performance Metrics services expose their own web pages and REST resources because not every operational question belongs to the Administration Service.

The browser path usually starts at Service Manager and then fans into a deployment console. Admin Client can also connect through Service Manager, which makes it feel familiar to anyone coming from GGSCI while still operating in the Microservices model. Direct REST access removes the human console entirely and targets the service namespace itself. These three entry points overlap in capability, but they have very different strengths when you care about auditability, repeatability, or blast radius under change control.

Human-first surface

Web UI gives rapid orientation and low-friction navigation.
Best for discovering what is deployed and what state it is in.
Weakest for durable automation.

Operator-first surface

Admin Client preserves CLI discipline and command sequencing.
Good for remote shells, jump hosts, and repeatable operating habits.
Less visual than browser-based service pages.

Automation-first surface

REST API is explicit, scriptable, and integration-friendly.
Best for platform tooling and idempotent pipelines.
Requires stronger discipline around tokens, roles, and error handling.

Section 02

Choose the access method by the work, not by habit

Teams often get into trouble by standardizing on a favorite interface instead of matching the interface to the task. The wrong access method does not always fail immediately. More often it produces avoidable friction: manual drift in the browser, fragile shell habits in runbooks, or over-engineered API calls for simple human checks.

Access method	Where it wins	What it costs	Use it when
Web UI	Fast visual orientation, process pages, topology discovery, service inspection.	Actions are manual; session behavior adds friction outside human workflows.	You need to understand the deployment quickly, inspect a process, or walk a less-frequent operator through a task.
Admin Client	Repeatable CLI operations, shell history, command bundling, remote terminal usage.	Less discoverable than the UI; still interactive unless you standardize execution discipline.	You are working from a bastion host, want predictable command order, or need a faster operating rhythm than a browser.
REST API	Pipelines, orchestration, external control planes, and machine-readable requests.	You must handle authentication, response codes, role boundaries, and service targeting deliberately.	You need repeatable automation, integration with external systems, or a contract that can be tested.

Use the web UI first when the problem is "What is here?"

That includes discovering deployments on a host, finding which service owns the problem, or inspecting process pages during an unfamiliar incident.

Use Admin Client first when the problem is "Do this sequence safely"

CLI workflows are easier to document, easier to repeat, and easier to narrow to a minimal change set than click paths in a browser.

Use the REST API first when the problem is "Make this reproducible"

If a task belongs in CI, a platform service, or a standard operational wrapper, direct HTTP calls are usually the cleanest long-term answer.

Section 03

Access prerequisites and boundaries that determine success before login

GoldenGate access starts failing long before a password prompt if the operator confuses host-level and deployment-level scope. Service Manager owns deployment inventory on a host. The deployment services own the actual process management and service-specific operations. You need both the right network path and the right mental map.

Prerequisites to confirm

The GoldenGate service you intend to reach is running and listening.
The deployment name is known and spelled correctly on multi-deployment hosts.
The user exists as a local GoldenGate user or an externally authenticated mapped user.
The user has the correct GoldenGate role for the operation, not merely valid credentials.
The client trusts the deployment certificate chain.

Boundary mistakes to avoid

Assuming a reachable Service Manager means Admin Service is reachable.
Assuming successful browser login means a REST client can reuse the session model.
Assuming a read-only user can start/stop processes because the UI loads.
Assuming Admin Client connections should omit the deployment name.
Assuming classic GGSCI habits map directly to Microservices service endpoints.

Why deployment targeting matters

If one Service Manager hosts several deployments, "I can connect" is only half a fact. You must also know which deployment becomes the default context, or specify it deliberately. Otherwise the session may be valid but aimed at the wrong administrative surface.

Shell Useful client-side variables before you start

# Keep the access surfaces explicit rather than typing hostnames ad hoc.
export SERVICE_MANAGER_URL='${SM_URL}'
export ADMIN_SERVICE_URL='${ADMIN_URL}'
export DEPLOYMENT_NAME='ledger_sync'
export GG_ADMIN_USER='ops_admin'
export OGG_CLIENT_TLS_CAPATH='/opt/ogg/client/ca'

That last variable matters when the client must be told explicitly where to find the trusted CA path. If certificate trust is wrong, the browser may show warnings, Admin Client may refuse the handshake, or REST calls may fail before they ever test identity.

Section 04

Working through the web UI: best entry point for orientation, not the default answer for everything

The browser experience begins at Service Manager because that is where Oracle GoldenGate exposes the host's deployment inventory and the launch points for service consoles. Once you enter a deployment, the Administration Service usually becomes the main page for Extract and Replicat work, while Distribution, Receiver, and Performance Metrics pages handle their own slices of the operating model.

Good web UI use

Use the browser when you need context before action: which deployments exist, which processes are running, which path is stalled, whether the lag problem is on capture, path transport, receiver intake, or apply.

What Service Manager gives you

Inventory of deployments on the local host.
Lifecycle control for deployments and services.
Launch links into individual service consoles.

What Administration Service gives you

Process administration for Extract and Replicat.
Checkpoint, local trail, and process-detail views.
The primary human console for most operations.

What the other service pages give you

Distribution path configuration and health.
Receiver intake visibility for incoming trails.
Performance and throughput analysis via PMSRVR.

What a clean browser-access flow looks like

Open the Service Manager address for the GoldenGate host.
Confirm that the expected deployment appears in the inventory.
Launch the deployment console rather than treating Service Manager as the process-management page itself.
Pivot into Administration Service for process work or into the specific service page that matches the problem domain.
Verify visible service state before making any change.

Signals you want immediately

The deployment is listed and reachable from Service Manager.
The correct services appear rather than a partial or stale inventory.
The process page reflects the deployment you intended to inspect.

Signals that should slow you down

The browser lands on Service Manager but not the deployment console.
Only some service pages load, suggesting partial service failure.
The UI is reachable but actions are blocked, which often means role mismatch.

Operational consequence

The web UI is excellent at showing state, but it is easy to overestimate how reproducible a browser-only operating practice is. If a change needs to be reviewed, repeated in another environment, or embedded in a maintenance sequence, the browser is often the discovery surface and not the long-term system of record.

Section 05

Working through Admin Client: the disciplined operator path into Microservices

Admin Client exists for teams that want Microservices access without giving up a terminal-driven operating style. It is not GGSCI pasted onto the new architecture. The important shift is that the shell connects into the Microservices environment, can target a Service Manager or deployment address, and then runs in the context established by that connection.

Why Admin Client matters

GoldenGate command-line habits remain valuable in Microservices, but they become safer when the connection target, deployment scope, and trust configuration are made explicit. Admin Client gives you that bridge.

Connection patterns that matter in practice

The most important Admin Client command is still the first one. Connection syntax can identify the service address, optionally choose a deployment, and then authenticate with a password alias, an explicit password, or a token. For identity-provider-enabled environments, token-based connection becomes especially important.

CLI Connect with a credential alias and explicit deployment

CONNECT ${SERVICE_MANAGER_URL} DEPLOYMENT ${DEPLOYMENT_NAME} AS ${GG_ADMIN_USER} PASSWORD ops_admin_alias

CLI Connect with token prompting

CONNECT ${SERVICE_MANAGER_URL} DEPLOYMENT ${DEPLOYMENT_NAME} AS api_ops TOKEN !

The bang suffix is important when you want a prompt instead of embedding a sensitive secret on the command line. That is a small operational detail with real security consequences because shell history, job wrappers, and process listings all become riskier if teams normalize inline secrets.

First verification after connection

CLI Verify service and process visibility

INFO ALL

INFO ALL is the fastest sanity check because it confirms more than simple authentication. It tells you whether the session landed in the deployment you intended and whether the key services and managed processes are visible from that context. If the login succeeds but the inventory looks wrong, you are dealing with a targeting problem, not a password problem.

Admin Client is strongest when

You work through jump hosts or secured terminal paths.
You want shell history and reviewable command order.
You need a fast human interface during maintenance windows.
You want the same operating rhythm across multiple deployments.

Admin Client becomes awkward when

The problem is visual and service-orientation is unclear.
You need machine-verifiable JSON contracts instead of shell output.
Authentication is delegated externally and your token refresh is immature.
The team treats it like GGSCI without accounting for service boundaries.

Failure pattern

A common mistake is to celebrate a successful connection string and skip the context check. On a host with multiple deployments, a valid shell in the wrong deployment is still operationally wrong.

Section 06

Working through the REST API: where GoldenGate becomes an automation surface

The REST API is the cleanest interface when the job belongs in code, a platform workflow, or a standard operational service. GoldenGate exposes versioned REST resources under the Microservices namespace, and current Oracle documentation positions bearer-token authorization as the normal request model for REST resources. That makes the API the right answer when you need explicit requests, structured responses, and integration points that do not depend on a human session.

REST is not "browser without pictures"

The UI uses session behavior appropriate for human navigation. The API expects deliberate authorization headers and service-specific resource paths. If you script the browser model instead of the API model, you create fragile automation.

Local-user JWT flow for API callers

For a locally managed GoldenGate user, Oracle documents a JWT generation flow through the authorization resource. After the token is obtained, subsequent requests present it as a bearer token. For externally authenticated users, the access-token story shifts toward the external identity provider, but the principle stays the same: the API wants an authorization token, not a UI session cookie.

Shell Request a JWT for a local GoldenGate API user

curl \
  --cacert ${CA_CERT} \
  --user api_reader:${LOCAL_USER_PASSWORD} \
  --header "Accept: application/json" \
  ${ADMIN_SERVICE_URL}/services/v2/authorizations/api_reader

Do not hard-code the token-generation response into documentation or wrappers if you have not validated the payload shape for your target release. The safe pattern is to retrieve the token from the documented authorization resource and then hand it to the calls that follow.

Shell Use the bearer token to query Extract inventory

export OGG_TOKEN='<access-token-from-authorization-resource>'

curl \
  --cacert ${CA_CERT} \
  --header "Authorization: Bearer ${OGG_TOKEN}" \
  --header "Accept: application/json" \
  ${ADMIN_SERVICE_URL}/services/v2/extracts

Shell Query Replicat inventory with the same token

curl \
  --cacert ${CA_CERT} \
  --header "Authorization: Bearer ${OGG_TOKEN}" \
  --header "Accept: application/json" \
  ${ADMIN_SERVICE_URL}/services/v2/replicats

These examples are intentionally read-oriented because the point here is access discipline, not speculative payload design. Once the token, base URL, and service scope are correct, the same pattern extends into lifecycle and configuration resources, with role requirements becoming more important as the operation moves from read to change.

Why platform engineers favor it

It is testable and version-controllable.
It integrates cleanly with schedulers and deployment pipelines.
It separates authentication from operator muscle memory.

Where teams get burned

They target the wrong service base URL.
They ignore token lifetime and refresh behavior.
They assume a successful read implies write authorization.

What good wrappers do

Fail loudly on 401 and 403 instead of retrying forever.
Make the deployment and service endpoint explicit inputs.
Log the intended action, not the secret-bearing header.

Section 07

Authentication, users, and GoldenGate roles are what turn access into action

Authentication tells GoldenGate who is connecting. Authorization decides what that identity may do. Oracle documents both locally managed users and externally authenticated users in GoldenGate Microservices. After the user exists, GoldenGate roles shape the real operating boundary. That means "I can log in" and "I can administer a deployment" are not interchangeable statements.

Role or identity element	Operational meaning	Why it matters for access methods
Local user	User managed directly in GoldenGate and usable for local auth flows.	Common in self-contained deployments; directly relevant for local JWT generation.
External user	User authenticated through an external provider and mapped to OGG.	Important for token-driven access designs and enterprise SSO patterns.
Administrator	Full access across the deployment.	Required for the highest-risk lifecycle and configuration operations.
Operator	Can perform most operations but with narrower change authority.	Often the right human role for day-two operations with separation of duties.
User	Primarily read-oriented role with limited control scope.	Fine for dashboards, listings, and low-risk inspection.

Subtle but common misread

A browser page or API resource returning successfully does not prove the user can perform the next step. Read access often succeeds long before change operations are allowed. Test the exact action boundary you care about before a maintenance window depends on it.

TLS and trust-chain consequences

Secure deployments are the normal production posture.
Self-signed environments create operator friction and validation ambiguity.
Admin Client and REST trust options must be aligned with the actual certificates.

Identity-design consequences

Human UI users and API users should not be the same account by default.
Token refresh strategy matters more as automation becomes critical.
Role assignment should reflect operational duties, not convenience during setup.

Section 08

What to verify after access is established

Successful authentication is not the end of the access workflow. For GoldenGate, the real validation step is proving that the session landed at the right scope, sees the expected services or processes, and can perform the class of action you intend. This is where mature operators separate connection success from operational readiness.

Method	Immediate verification	Healthy signal	What the signal means
Web UI	Open Service Manager, launch target deployment, inspect service page.	Deployment inventory is correct and service console loads cleanly.	Host-level entry, deployment launch, and service consoles are aligned.
Admin Client	Connect and run `INFO ALL`.	Correct services and managed processes are listed for the deployment.	The shell is authenticated, scoped correctly, and seeing live state.
REST API	Use bearer token on a low-risk inventory endpoint (Extracts/Replicats).	API returns inventory from expected deployment and service scope.	The token, TLS trust, and base resource path are working together.

Verification for a human-run maintenance window

Prove three things before the change starts: you can enter the deployment, you can see the right processes, and the account has the role needed for the planned operation. That last point is usually skipped until it hurts.

Verification for an automated control path

Test the token path, the target base URL, and one harmless read endpoint in the same runtime that will execute the change. A passing curl command on an engineer laptop does not validate the automation host.

Section 09

Failure patterns and the shortest useful recovery path

GoldenGate access incidents are easier to resolve if you stop treating them as generic "login failures." The symptom usually points to a narrower class of mistake. That means you can often recover access faster by checking boundary assumptions than by rotating passwords or restarting services blindly.

Symptom	Most likely cause	What to inspect first	Next useful action
Browser reaches Service Manager but not deployment console	Deployment service is unavailable or launch path points to wrong state	Service Manager inventory and status of deployment services	Confirm deployment is up, then isolate which service is broken
Admin Client connects but shows wrong deployment context	Implicit default deployment selection on multi-deployment host	Connection target and whether `DEPLOYMENT` was specified	Reconnect with deployment named on command line and run `INFO ALL`
REST read calls fail with auth errors	Missing/expired bearer token, or token for wrong identity path	Auth header handling, token freshness, local-vs-external flow	Regenerate or refresh the token deliberately; do not loop retries
Authentication succeeds but changes are denied	GoldenGate role mismatch	Assigned GoldenGate role for the connected user	Validate if action needs Operator/Administrator authority and adjust
Browser warns on trust or REST/CLI TLS neg fails	Client trust chain does not match deployment certificates	Client-side CA trust config and cert presented by service	Correct trust configuration; do not normalize insecure bypasses

What not to do during access incidents

Do not switch interfaces randomly and call that troubleshooting. If the browser fails, the shell fails, and the API fails, the common layers are usually service availability, trust, identity, or role assignment. Change one variable at a time and verify scope after each attempt.

Section 10

Version-aware interpretation: what stayed stable and what changed around it

Some of the most confusing GoldenGate articles mix long-standing access concepts with older naming and newer security behavior as though they were the same thing. They are not. The safe interpretation is to separate the durable architecture from the version-era details.

What stayed stable

Microservices is the modern architecture for browser-based, API-based, and Admin Client administration.
Service Manager remains the host-level manager for deployments.
Administration Service remains the main process-management surface inside a deployment.
Admin Client remains the CLI bridge into the Microservices control plane.

What changed around it

Older material frequently says "server" where current documentation says "service."
Current documentation emphasizes bearer-token authorization for REST resources.
IDP-enabled deployments make token-based access more central than in early MA examples.

Practical modern baseline

If you are designing day-two operating practice now, treat GoldenGate Microservices as the primary baseline. Classic architecture knowledge is still useful for legacy estates, but the three access methods in this article are specifically about the Microservices operating model.

For DBA-led operations teams

Use the browser to orient, Admin Client to execute repeatable human changes, and the API only when the task truly belongs in a reusable wrapper or platform process.

For platform and automation teams

Design around service-specific API endpoints, explicit bearer-token handling, clear role boundaries, and a documented fallback path through Admin Client or UI when automation fails.