Oracle Transaction Manager for Microservices
Oracle Transaction Manager for Microservices, also known as "MicroTx", simplifies application development and operations by enabling distributed transactions to ensure consistency across microservices deployed in Kubernetes.
Oracle Backend for Microservices and AI includes the free version of MicroTx, which has all of the functionality of the commercial version, but limits the number of transactions and only persists data in memory. It is recommended for evaluations and application development purposes.
MicroTx supports the following consistency models:
- Extended Architecture (XA)
- Long Running Actions (LRA)
- Try-Confirm/Cancel (TCC)
Use Oracle Transaction Manager for Microservices with Spring Boot
To use MicroTx in your Spring Boot applications, include the following dependency in your pom.xml or equivalent:
<dependency>
<groupId>com.oracle.microtx.lra</groupId>
<artifactId>microtx-lra-spring-boot-starter-3x</artifactId>
</dependency>
Add the following configuration to your Spring application configuration. The variables in this configuration are automatically injected into your deployment and pods when you deploy applications to Oracle Backend for Microservices and AI using the OBaaS deployment Helm chart.
spring:
microtx:
lra:
coordinator-url: ${MP_LRA_COORDINATOR_URL}
propagation-active: true
headers-propagation-prefix: "{x-b3-, oracle-tmm-, authorization, refresh-}"
lra:
coordinator:
url: ${MP_LRA_COORDINATOR_URL}
Components and enablement
The MicroTx installation is made up of three components, each of which can be enabled or disabled independently in the Helm values:
otmm.coordinator— the transaction coordinator (XA/LRA/TCC).otmm.workflowServer— the workflow server (see below).otmm.console— the web console used to monitor transactions and workflows.
All three are enabled by default. To disable a component, set its enabled flag to false:
otmm:
coordinator:
enabled: true
workflowServer:
enabled: true
console:
enabled: false
The console exists only to front the coordinator and workflow server, so it is deployed only when at least one of those two components is enabled. If both otmm.coordinator.enabled and otmm.workflowServer.enabled are false, the console is not deployed even if otmm.console.enabled is true. When deployed, the console is connected only to the backends that are enabled, so a coordinator-only or workflow-only install does not leave the console pointing at a service that was not deployed.
Identity provider and JWT security
Configure MicroTx security under otmm.commonConfiguration.security. The
identity-provider fields follow the MicroTx 26.1 identity-provider
properties.
Use serverType: idcs for Oracle IDCS and other for other supported providers.
Copy issuer and jwksUri from the provider's discovery document. Leave scopes
empty for non-IDCS providers; IDCS defaults to openid groups.
For example, a Keycloak configuration with console access is:
otmm:
commonConfiguration:
externalURL:
protocol: https
host: microtx.example.com
security:
enabled: true
clientSecretName: microtx-client
identityProvider:
serverType: other
issuer: https://idp.example.com/realms/obaas
jwksUri: https://idp.example.com/realms/obaas/protocol/openid-connect/certs
identityProviderUrl: https://idp.example.com/realms/obaas
audience: microtx
scopes: ""
roleMappings:
coordinator:
adminUserRoles: microtx-admin
adminUserRolesPath: "realm_access, roles"
workflow:
claimsRolePaths: realm_access.roles
roles:
admin: microtx-workflow-admin
coordinator:
authentication:
requestsWithNoJWT: DENY
console:
cookieEncryptionPasswordSecretName: microtx-console-cookie
Prepare namespace-local Secrets: microtx-client with clientId and
clientPassword, and microtx-console-cookie with secret. Register the console
redirect URI https://microtx.example.com/console/oidc/redirect with the IdP,
and configure the audience and roles in the tokens. The IdP must be reachable by
MicroTx pods and by users' browsers. Set up the corresponding HTTPS route;
externalURL alone does not provision it.
Console cookie encryption is configured separately through
otmm.console.cookieEncryption.enabled. It defaults to false to preserve
existing console behavior. Set it to true to enable the console's cookie
encryption setting and verify browser login with your encryption-password Secret.
When common security and the console are enabled, the chart still requires
cookieEncryptionPasswordSecretName, regardless of this setting.
Common security enables coordinator RBAC, workflow JWT validation, and console
OIDC. An empty coordinator.authentication.requestsWithNoJWT derives DENY when
security is enabled and ALLOW otherwise. ALLOW with coordinator RBAC enabled
is rejected. For JWT authentication without common RBAC, explicitly set DENY
and provide issuer/JWKS details and the expected access-token audience. The chart
exports identityProvider.audience as the coordinator's JWT_AUDIENCES setting.
API-only installations can disable the console and omit its client Secret, URL,
and administrator role settings; coordinator JWT authentication still requires
the audience.
The evaluation defaults leave security disabled; enable security and require
JWTs in production, as described in MicroTx authentication
properties.
Use identityProvider.roleMappings.coordinator for administrator roles and
identityProvider.roleMappings.workflow for workflow roles. Coordinator role
paths use commas; workflow paths use dots. Older OBaaS overrides under
identityProvider.adminUserRoles, identityProvider.adminUserRolesPath,
identityProvider.policy, and workflowServer.security.identityProvider.policy
remain supported and take precedence. Remove those overrides when migrating to
the documented roleMappings paths.
JWT validation and RBAC do not enable token propagation to participant callbacks. The chart keeps token propagation disabled; enabling it requires additional encryption-key and callback configuration. After deployment, verify that missing, expired, incorrectly signed, and wrong-issuer tokens are rejected, and that administrator APIs enforce the configured roles. Helm render checks do not establish runtime IdP compatibility.
Coordinator database storage
The coordinator defaults to otmm.coordinator.storage.type: memory. To persist
transaction state across coordinator restarts, use db with a MicroTx Enterprise
Edition image. The Free coordinator image does not support database storage.
Database storage does not require a coordinator PVC and does not migrate
transactions previously held in memory.
Before installing, prepare a reachable Oracle Database and grant the storage user MicroTx's required privileges and tablespace quota. Follow the database setup prerequisites, including separate schemas for the coordinator and workflow server when both use Oracle Database. Accept the applicable Enterprise Edition image terms and provide an image pull secret if required by Oracle Container Registry.
Reuse the OBaaS database credentials
For a coordinator-only installation, layer these overrides after your normal OBaaS values:
otmm:
coordinator:
image:
repository: container-registry.oracle.com/database/microtx-ee-coordinator
tag: "26.1.2"
storage:
type: db
db:
credentialSecretName: ""
workflowServer:
enabled: false
With credentialSecretName empty, the coordinator uses the same application
credential secret as the database metrics exporter. This includes custom secret
names and keys configured through database.authN. The application secret's
service key supplies the connection string; optionally override it with
otmm.coordinator.storage.db.connectionString.
The chart also reuses the exporter's database wallet and mounts it at
/etc/config/dbwallet. It overlays sqlnet.ora to point to that directory without
changing the shared Secret. No separate JSON credential Secret is needed: the
chart serializes the application username and password at startup. Custom
coordinator images using this path must provide Python 3 and /app/tcs.
Use a separate coordinator schema
When the workflow server is enabled, keep its OBaaS application schema separate
from the coordinator's transaction-store schema. Create a Secret in the OBaaS
application namespace for the coordinator user. Its secret key must contain JSON
in this format:
{"username":"<coordinator-user>","password":"<coordinator-password>"}
Create it from a protected local file rather than placing credentials in a committed values file:
kubectl -n <application-namespace> create secret generic microtx-coordinator-db \
--from-file=secret=<credential-json-file>
Keep the Enterprise Edition image override above and configure:
otmm:
coordinator:
storage:
type: db
db:
credentialSecretName: microtx-coordinator-db
credentialSecretKey: secret
connectionString: "<coordinator-connect-string>"
# Set one of these when the connection requires a wallet:
# walletSecretName: "<coordinator-wallet-secret>"
# walletConfigMapName: "<coordinator-wallet-configmap>"
A separate credential Secret requires an explicit connection string. It does not
implicitly select the shared OBaaS wallet: supply walletSecretName or
walletConfigMapName when needed, in the application namespace. The wallet is
mounted at /etc/config/dbwallet; its sqlnet.ora must use that wallet directory.
The chart does not rewrite custom wallet configuration.
Schema initialization and verification
For database storage, otmm.coordinator.storage.db.initializeSchema defaults to
true. The initialize-coordinator-schema init container runs the selected image
in MicroTx initialization mode with the same credentials and wallet as the
service. The coordinator starts only after initialization succeeds. This step can
create or upgrade database objects; review MicroTx's migration requirements and
back up an existing transaction store before upgrading its image.
If a DBA provisions and upgrades the schema separately, set
otmm.coordinator.storage.db.initializeSchema: false.
After the Helm installation or upgrade, check both containers:
kubectl -n <application-namespace> logs <app-release>-otmm-tcs-0 \
-c initialize-coordinator-schema
kubectl -n <application-namespace> logs <app-release>-otmm-tcs-0 -c otmm-tcs
Initialization should complete successfully and the coordinator should report
serving.... If startup reports ORA-00942 for OMTM_STATS, check schema
initialization and the storage user's privileges. For ORA-28759, check that the
wallet files are readable and sqlnet.ora points to their mounted directory.
MicroTx Workflow Server
The MicroTx Workflow Server extends transaction coordinator with advanced workflow capabilities.
For MicroTx sizing and deployment guidance, see the official Oracle Transaction Manager for Microservices 26.1 documentation. To enable the workflow server in OBaaS, set the otmm.workflowServer.enabled property to true in the Helm values:
otmm:
workflowServer:
enabled: true
When the workflow server is enabled, it uses the OBaaS application database secret, typically <release>-db-authn, and runs Flyway against that schema during startup. The database init job grants OBAAS_USER the schema privileges required for this initialization. If a pre-existing application user is supplied through database.authN.secretName, that user must have equivalent schema DDL privileges and quota on its default tablespace.
Upgrading to the commercial version
If you have licensed Oracle Transaction Manager for Microservices Enterprise Edition (EE), upgrade the MicroTx components as follows:
- Transaction Coordinator: Replace the Free container image with the EE container image from Oracle Container Registry. You must also configure persistence when upgrading to EE. Follow the Set Up Oracle Database as Data Store instructions.
- Workflow Server: Replace the Free container image with the EE container image from Oracle Container Registry.
- Console: Replace the Free container image with the EE container image from Oracle Container Registry.