Oracle Integration MCP Gateway: Preserve Corporate User Identity with JWT User Assertion
Preserving corporate identity means ensuring that the person who initiates an AI-assisted business request remains identifiable when the request reaches the system that owns the data or transaction.
In Oracle Integration 3, this requires more than selecting an OAuth security policy. The caller's identity must travel through supported identity-propagation mechanisms, the relevant tokens must be issued for the correct recipients, and the target application must enforce that user's permissions.
Consider a procurement assistant. An employee asks which purchase orders they can access. Another employee uses the same assistant, the same gateway, and the same integration, but has different purchasing permissions. The system must not treat both requests as the same employee merely because they share an integration or technical connection.
This tutorial follows a fictional procurement scenario to explain the identity choices, JWT claims and signing material, identity-application preparation, REST Adapter configuration, Subject mapping, MCP server configuration, and the evidence required to verify access using two corporate test users.
📑 In This Post
- Choose the right identity model
- Understand the end-to-end trust boundaries
- Understand JWT claims, signing material, and trust
- Prepare identity applications, grants, and certificates
- Configure the REST invoke connection and map Subject
- Configure the MCP server and gateway
- Verify propagation with two corporate users
- Common mistakes and targeted troubleshooting
- Enterprise rollout considerations
- FAQ
- References and further reading
- Summary
🔀 Quick Comparison: Service Identity vs End-User Identity
| Decision point | Service identity | End-user identity |
|---|---|---|
| Meaning | The request represents an authorized application or service account. | The request preserves the identity of the employee or other user who initiated it. |
| Typical token design | An application obtains a token using a service-oriented grant such as client credentials. | The caller obtains a token in the user's context; supported downstream exchanges preserve that identity. |
| Target authorization | The target primarily evaluates the service account's privileges and any additional trusted business rules. | The target can evaluate the effective user's privileges, provided its authorization model supports them. |
| Audit interpretation | An event may identify the technical caller rather than the employee who initiated the request. | The target can record the effective user when supported propagation and auditing are correctly configured. |
| Main trade-off | Operational simplicity, but potentially broader shared access. | Stronger per-user authorization and accountability, with more identity, trust, and lifecycle dependencies. |
Neither approach is universally correct. A scheduled integration that processes records under an explicitly approved technical account may be designed around service identity. An assistant that answers questions about an employee's own purchase orders usually needs a stronger per-user authorization model.
01
Choose the Right Identity Model
A useful starting question is not, “Which OAuth policy should I select?” It is, “Whose permissions must the target evaluate when this business request arrives?” The answer determines the identity design that follows.
Analogy: An employee badge versus a shared department badge
Imagine two employees entering a procurement office. With individual identity, the receiving system checks each employee's own permissions. With a shared department badge, the system recognizes the department's access rather than automatically identifying the person holding it. Adding an employee's name to a form does not transform the shared badge into an individual credential.
In OAuth, a grant type describes how an application obtains an access token. An access token is a credential presented to a protected resource. A subject identifies the principal represented in a particular security context. These concepts are related, but none automatically proves that a downstream service receives the original employee identity.
Service identity is a reasonable choice when:
- The business requirement explicitly permits a technical account to perform the activity.
- The application is responsible for enforcing the business rules that distinguish records or actions.
- The target does not require delegated per-user access, and that restriction has been reviewed and approved.
End-user identity is the stronger fit when:
- Different employees must receive different results from the same tool.
- The target application is expected to enforce individual record, department, or transaction permissions.
- Audit evidence must identify the effective user rather than only a shared integration account.
Oracle Integration's documented identity-propagation use case uses OAuth JWT user assertion as part of the route between the MCP gateway, MCP server, tool-registered integrations, and an endpoint system. The use case also shows the runtime caller's identity reaching the endpoint despite different usernames configured during design time. See the Oracle identity-propagation use case.
Preserve the authenticated identity from a trusted security context. Do not substitute a username supplied as an ordinary MCP tool argument.
For the running example, the tool accepts a purchase-order identifier such as PO-4101. It does not accept a model-selected employee identifier to decide whose permissions apply. The identity comes from the caller's authenticated context and the configured propagation path.
Safety Check
Risk: Two employees unintentionally receive the permissions of the same technical account.
Control: Select the intended identity model, preserve a trusted user subject when required, and enforce authorization at the target.
Remaining risk: A correctly identified user can still have excessive permissions, and an intermediary can still have authorization or mapping defects.
You need to decide whether an AI assistant should operate as a technical service or as the employee whose business data is being accessed.
02
Understand the End-to-End Trust Boundaries
The MCP gateway and MCP server are related but distinct components. The gateway governs access to configured servers and policies. A project MCP server can expose registered Oracle Integration integrations as callable tools. The integration executes the business workflow, and the target system makes its own authorization decisions.
A token is issued by an authorization server and presented to a protected resource. It is not sent to the gateway merely to ask the gateway to issue a token. This distinction becomes especially important when an identity passes through several components.
| Hop | What happens | Trust and enforcement owner |
|---|---|---|
| 1. User to host/client | The employee authenticates to the application that provides the assistant. The host/client obtains or uses the authorized caller's access token. | Identity provider and application authentication design. |
| 2. Client to gateway | The MCP client presents a token to the gateway endpoint. The gateway evaluates the token and its applicable audience and permissions. | Selected gateway authorization mode and the configured resource server or Oracle Integration authorization model. |
| 3. Gateway to project MCP server | The gateway routes the request to the configured server using that connection's security configuration. With JWT user assertion, a separately configured assertion/token exchange participates in the trust path. | Gateway server registration, assertion configuration, authorization server, and project-server permissions. |
| 4. Project MCP server to integration | The project server exposes the registered integration as an MCP tool. The MCP request invokes that tool; the integration then runs its configured workflow. | Tool registration, project/server exposure, integration activation, and its configured trigger security. |
| 5. Integration to target | The integration maps the trusted originating Subject to the downstream invoke's Subject. The REST Adapter obtains authorization using its own security configuration and calls the target. | REST invoke security configuration, identity-domain trust, mapped subject, and target application. |
| 6. Target decision | The target checks the effective identity's access to the requested purchase order and returns the result or rejects the request. | Target authentication, authorization, record-level rules, and audit trail. |
The important distinction is that these hops do not automatically share one bearer token. The original client-to-gateway token, gateway-to-server authentication, and integration-to-target token exchange have different recipients and responsibilities. Oracle documents a supported propagation path; that does not mean an incoming bearer token can be forwarded unchanged to every downstream service.
Worked Example: One request, three different security checks
An employee asks, “Can I view purchase order PO-4101?”
- The client proposes a read-tool call and sends the MCP request. The model proposes the tool and arguments; the client executes the protocol request.
- The gateway validates access to its endpoint and routes the permitted tool request. Gateway authorization does not by itself prove that the employee may view PO-4101.
- The OIC integration maps the trusted incoming Subject to the REST invoke's Subject. Its downstream authentication flow must be able to represent that user.
- The target evaluates the effective user and the requested record. The result becomes the tool result that the client returns to the host, where it can be presented to the employee.
For a concrete tool contract, the following metadata is illustrative; the actual identifier and input schema must come from the tool registration and current server discovery.
Illustrative tool metadata — not a live discovery response
{
"name": "GetPurchaseOrderForCurrentUser",
"description": "Retrieves one purchase order that the authenticated caller is allowed to view.",
"inputSchema": {
"type": "object",
"properties": {
"poId": {
"type": "string",
"minLength": 1,
"description": "Purchase-order identifier to look up."
}
},
"required": [
"poId"
],
"additionalProperties": false
}
}Example business arguments — not a complete MCP request
{
"poId": "PO-4101"
}Here inputSchema is a JSON Schema describing an object with one required string field. The example deliberately disallows extra properties, including a caller-selected userId. This is a proposed teaching contract, not evidence that Oracle generated the same schema. Inspect the actual gateway discovery result: the MCP tool name used for invocation may differ from an OIC display label. A valid argument shape still does not grant access to the requested record.
Notice what is missing: a client-supplied userId. The user identity must come from the trusted security path, not an argument that the model can select or invent. The actual tool identifier, description, and schema must be inspected before attempting a real invocation.
Safety Check
Risk: A downstream system accepts a token intended for another service or trusts a caller-controlled identity field.
Control: Validate the intended audience at the relevant hop, use the documented identity-propagation path, and keep authorization in the target.
Remaining risk: Correct token validation does not establish that the tool's business behavior or the user's record permissions are correct.
03
Understand JWT Claims, Signing Material, and Downstream Trust
A JSON Web Token (JWT) carries claims: statements about an issuer, subject, recipient, or related security context. A signed JWT can provide integrity and authenticity when its signature and claims are properly validated. Decoding a token and reading its fields is not the same as verifying its signature or proving that its claims are acceptable.
A JWT used as an OAuth user assertion is not the same thing as the access token eventually presented to the protected API. The assertion is presented to the authorization server in a configured grant flow. After validating the client, assertion, audience, signature, and other applicable requirements, the authorization server may issue an access token for the requested resource.
Claims and identifiers that must not be confused
| Field | Meaning | What to verify |
|---|---|---|
iss |
Issuer: the entity making the assertion. | The configured issuer identifier is recognized by the receiving authorization server. |
sub |
Subject: the principal represented by the assertion, under the issuer's rules. | The runtime user identifier maps to the identity the receiving system recognizes. |
aud |
Audience: the intended recipient or recipients of the token/assertion. | Use the value expected by the authorization server for this particular assertion flow. Do not reuse a gateway audience without checking. |
exp and iat |
Expiration and issued-at time. | The timestamps are valid, use the expected format, and satisfy the recipient's time and lifetime requirements. |
nbf |
Not-before time, when included. | The assertion is not being used before the permitted time. |
jti |
JWT ID: an identifier for a particular token. | Where required, use a unique value and the recipient's documented replay-protection rules. |
Header kid |
Key ID: identifies the signing key associated with the signature. | Match the key identifier to the correct public certificate/trust configuration. It is not the token's jti. |
Header alg |
The signature algorithm. | Use an algorithm explicitly supported and required by the relevant Oracle/identity-provider configuration. Oracle's documented JWT user-assertion example specifies RS256. |
JWT fields have defined meanings in the IETF's JSON Web Token specification, RFC 7519. The OAuth JWT bearer assertion profile is described separately in RFC 7523. Oracle's identity-domain configuration determines which claim values and grant settings are accepted in a particular deployment.
A subtle but important distinction: kid and jti
Suppose your gateway connection configuration has a field called Signing Key ID, and the identity domain has a public certificate registered for the client application.
That field concerns the key used to verify the signature. In JWT terminology, the corresponding header identifier is kid. The claim jti instead identifies the individual JWT. Oracle's MCP server property description can be read ambiguously when it describes the key identifier as a JWT identifier; use the actual key/certificate configuration, not an independently generated token ID, to populate the signing-key reference.
Keep three names separate: the OIC private-key alias locates signing material in Oracle Integration; the identity-domain certificate key identifier locates the trusted verification certificate; and the JWT payload jti identifies one assertion. The first two may use the same spelling in a tutorial but serve different registries. Confirm the certificate/key relationship rather than substituting a fresh jti into Signing Key ID. The signed-header kid is defined in RFC 7515, not as a JWT payload claim.
Audience deserves similar care. The JWT assertion's audience identifies its intended authorization server. The access token used at a protected resource has its own recipient requirements. The two should not be assumed equal. Oracle documentation examples contain differing identity-domain audience strings, so the exact value must be confirmed for the relevant domain and configured grant rather than copied from an example.
What the signing material actually does
- The trusted client signs the assertion using its private signing key.
- The receiving identity service checks the assertion against the registered public certificate and applicable claim requirements.
- If validation and authorization succeed, the identity service can issue an access token under the selected grant and requested scope.
- The downstream resource validates the token intended for it and applies the permissions associated with the effective identity.
A JWT user assertion used as an authorization grant represents the asserted user; a JWT client assertion authenticates the OAuth client. They can coexist but have different subjects and protocol roles. Selecting a policy whose name contains JWT does not establish end-user propagation. An ID token issued for a login client is also not a substitute for the API access token required by the gateway.
A private key is not a user identity. It establishes that an assertion was signed by the party holding that key. The asserted subject, trust relationship, grant, requested scopes, and downstream permission checks determine what the resulting credentials can represent and access.
Safety Check
Risk: An accepted signature is incorrectly treated as proof that the asserted user is authorized for every downstream operation.
Control: Validate the signature, claim semantics, recipient, grant, scope, and target-system permissions as separate checks.
Remaining risk: An overly privileged trusted client can still assert identities that it should not be allowed to represent. Restrict and monitor the client and its signing material.
04
Prepare Identity Applications, Grants, and Certificates
Oracle's documented flow involves trust material and OAuth configuration in more than one place. Before opening the console, separate the registration used for the end-user's gateway access from the registration and signing setup used to obtain downstream access tokens.
These are different security purposes. For an interactive test, the employee needs a token in their own context. For a JWT user assertion exchange, the trusted client needs the correct assertion configuration and signing material. An organization may be able to combine functions in an appropriately configured application, but distinct registrations are a useful least-privilege design where the environment supports them.
Prerequisite gates
- Have access to the correct identity domain, the relevant Oracle Integration project, and the permissions needed to manage applications, signing certificates, integrations, and gateway configuration.
- Have an active nonproduction integration with a REST trigger and a REST Adapter invoke connection to a test target that supports the required delegated or user-assertion trust.
- Have two synthetic test users and target records with deliberately different access permissions.
- Have the project MCP server enabled and a documented server endpoint available. The gateway connects to that server; the final MCP client connects to the gateway endpoint.
The process below does not require provisioning a new Compute virtual machine. The gateway is a managed Oracle Integration capability. An existing VM is neither the gateway itself nor a prerequisite for the managed gateway workflow.
Milestone A — Prepare the JWT assertion client application
Start here: Oracle Cloud Console, in the intended identity domain. The signing-key pair and public certificate must be prepared using your approved key-management process.
Navigation: Identity & Security > Domains > select the compartment and identity domain > Integrated applications.
Steps
- Generate or obtain the approved signing-key pair. Retain the private key only in the approved secure process. Export the public X.509 certificate in the format required by the identity domain.
- Open Integrated applications and select Add application.
- Choose Confidential Application, then select Launch workflow.
- Enter a descriptive application name such as
PROCUREMENT-MCP-JWT-TEST. This is a tutorial name, not a required Oracle identifier. - Select Submit to create the application. Open the application's OAuth configuration tab and then Edit OAuth configuration.
- Select Configure this application as a client now. Under Allowed grant types, select JWT assertion. Include any additional grant only when required by the current use case and documented configuration.
- For the JWT assertion setup described by Oracle's REST Adapter documentation, configure the client as a trusted client and import the public certificate where the supported workflow requires it. Confirm the actual fields presented by your identity domain.
- Save or submit the OAuth configuration and complete any required application activation action before using it.
Expected result: The intended application exists and is configured for the required JWT assertion flow. Its client identifier is available to authorized administrators, and the public certificate is registered as required.
If this fails: Stop before configuring OIC. Check the identity domain, grant-type selection, certificate format, and the intended issuer/audience values with the identity administrator. Do not compensate by disabling signature checks.
Before activating the assertion client, configure its authorized resource scopes in OAuth configuration using the actual resource application. Oracle's OIC prerequisite example includes instance scopes ending in urn:opc:resource:consumer::all and ic/api/; use the full values from the intended instance and determine which are required for the selected endpoints. These are service-instance scopes, distinct from dedicated gateway tools:list/tools:call scopes. For the procurement target, separately register the assertion client with that target's authorization server and grant its required resource scopes and user permissions.
Oracle's REST Adapter guide also describes registering the certificate in the identity domain's trusted-partner certificate area. That trust configuration is separate from merely possessing a certificate file and must not be skipped if the applicable flow requires it.
Milestone B — Register the certificate as a trusted partner
Start here: The same intended identity domain, after the public certificate is available and the JWT assertion client application has been created.
Navigation: Open the identity domain, then select Security and locate Trusted partner certificates.
Steps
- Open the identity domain's Security area.
- Locate Trusted partner certificates.
- Select Import certificate.
- Import the public certificate corresponding to the intended signing key and finish the import workflow. Confirm that the expected certificate appears in the trusted-partner list.
Expected result: The public certificate is present in the intended identity domain's trusted-partner certificate list.
If this fails: Check that the certificate belongs to the correct key pair and identity domain. A similarly named certificate from another environment is not interchangeable evidence of trust.
Milestone C — Upload the signing key to Oracle Integration
Start here: The intended Oracle Integration service instance, with the matching signing material available in a format accepted by the current product.
Navigation: Oracle Integration > Settings > Certificates.
Steps
- Open Settings, then select Certificates.
- Select Upload.
- Enter a controlled alias such as
procurement_user_assertion_key. This tutorial alias is illustrative; the required value is the alias that all relevant connection and gateway settings will reference. - In Type, select Signing key.
- Select Private and upload the signing private-key file for this outbound assertion flow. Oracle documents PKCS1 and PKCS8 formats for Signing key uploads. An X.509 public certificate alone cannot sign, and a JKS or PKCS12 container is not a substitute for the required signing-key file. Convert material through the approved key-management process if needed; keep the matching public certificate for identity-domain trust.
- Complete the upload, including the password field if the uploaded private signing key is encrypted.
- Confirm that the uploaded key appears in the certificate list under the intended alias.
Expected result: The relevant signing key is available to Oracle Integration under the selected alias.
If this fails: Stop and verify key format, certificate type, alias consistency, and the key's environment ownership. Never upload or replace a production key merely to make a test pass.
The identity-propagation workflow documented by Oracle uses the same signing-key alias in its relevant MCP server and REST Adapter invoke configuration. This is a configuration dependency: the alias must point to the intended signing material, not just have a similar name.
Oracle's OIC invocation prerequisites document ServiceInvoker assignment for the relevant user or application context. This does not mean that ServiceInvoker authorizes every OIC Developer API operation, or that it grants procurement-record access. Check the roles required by each actual endpoint. User-context access requires the test users/groups to have the appropriate OIC invocation permissions; granting an application a role alone does not establish each employee's target permissions.
Prepare the interactive caller application separately
The JWT assertion client above does not by itself configure the employee login flow. For the documented caller test, use a confidential application configured for Authorization Code in the intended identity domain. Keep this user login registration distinct from the downstream assertion trust when that improves ownership and privilege control.
- In the caller application's OAuth configuration, enable Authorization code. Configure Refresh token only as required by the selected documented workflow and session lifecycle; do not add every available grant.
- Register the exact callback/redirect URI required by the actual MCP test client. A callback shown for an OIC adapter connection is not automatically the callback of Postman or another host. Obtain the client callback value and match its registered URI; do not copy a different application's example.
- Assign the actual resource scopes and permitted users/groups for the confirmed gateway authorization design, submit the configuration, and activate the application. Keep the client secret in the confidential client's protected configuration.
- Use that client's supported Authorization Code workflow to sign in as each employee, with its required request-correlation and callback protections. The client exchanges the code for the access token; the employee password must not become a tool argument. Verify which user session supplied the token before each test.
If the target uses a different identity domain, agreeing on an email spelling is insufficient trust. Confirm the target-recognized subject format, account mapping or federation, allowed issuer, certificate, and delegated permissions.
05
Configure the REST Invoke Connection and Map Subject
This is the key integration-level step. A REST Adapter invoke connection using OAuth JWT user assertion establishes the downstream token-acquisition mechanism. The mapper determines which originating user's identity is carried into that downstream invocation.
These two settings solve different problems. A correctly configured signing key cannot compensate for a missing Subject mapping. A correct mapping cannot compensate for an untrusted certificate, incorrect audience, or missing target permission.
Milestone D — Configure the REST invoke connection for JWT user assertion
Start here: Oracle Integration, in the project that contains the existing nonproduction integration. The REST trigger, target API, and associated test identity configuration must already exist.
Navigation: Open the relevant project workspace, then locate the Connections section and the REST Adapter invoke connection.
Steps
- Open the intended REST Adapter invoke connection.
- Review the REST API base URL and confirm that it targets the nonproduction API that is configured to accept the intended delegated identity flow.
- Under Security, select OAuth using JWT User Assertion. Confirm that this is the intended policy for the target rather than a different OAuth policy that represents a service account.
- Supply the Access Token URI provided for the target's authorization server. Do not copy another tenant's token endpoint.
- Upload or select the JWT header and payload configuration required by the connection's documented interface. Verify the assertion claims against the applicable identity-domain requirements.
- Set JWT Private Key Alias to the alias of the matching signing key uploaded under Settings > Certificates.
- Configure the required scope and any other mandatory security properties using values supplied by the target's authorization design.
- Run the documented connection test if available. Stop if it fails.
- Save the connection configuration after the test and required settings are satisfactory.
Expected result: The invoke connection is configured with the intended JWT user-assertion policy and key alias. A successful connection test is evidence of a working connection under the tested configuration, not proof that two different employees will receive their distinct target permissions.
If this fails: Check the access-token URI, expected audience, issuer/client registration, key alias, certificate trust, scope, and target API. Do not proceed to identity-isolation testing until the connection-level failure is understood.
Prepare valid JSON files, not a finished signed token. Oracle's REST Adapter outbound prerequisites require iss, exp, sub, and aud in the uploaded payload configuration. They state that iat, exp, nbf, and jti, when present, are calculated dynamically and replace manually supplied values. This behavior concerns the REST Adapter configuration; do not generalize it to every JWT library or gateway property.
Header JSON skeleton — replace the certificate identifier
{
"alg": "RS256",
"typ": "JWT",
"kid": "REPLACE_WITH_REGISTERED_CERTIFICATE_KEY_ID"
}Payload JSON skeleton — configuration only, not a token to submit manually
{
"iss": "REPLACE_WITH_ASSERTION_CLIENT_ID",
"sub": "REPLACE_WITH_VALID_DESIGN_TIME_TEST_SUBJECT",
"aud": "REPLACE_WITH_CONFIRMED_ASSERTION_AUDIENCE",
"exp": 0,
"iat": 0,
"nbf": 0,
"jti": "ADAPTER_GENERATES_THIS_VALUE"
}Replace every REPLACE_WITH value with the approved configuration before upload. The zero time values above mark adapter-generated fields; they would describe an unusable assertion if submitted unchanged to a token endpoint. Do not sign or send this skeleton as a manual JWT. Runtime propagation must still override the relevant user through the supported Subject mapping and be proved with both callers. For a manually created test assertion, generate valid current NumericDate values in seconds, a short provider-approved lifetime, and a fresh identifier where required. Never copy dates or token IDs from documentation examples.
JWT time claims use NumericDate seconds, not JavaScript-style epoch milliseconds or a local date string. Allow only the receiving service's documented clock tolerance. Audience comparison can be exact: a trailing slash or a different hostname is not cosmetic. A signed JWT is not thereby encrypted; avoid unnecessary personal data and never paste live tokens into public decoding tools.
Oracle's REST Adapter documentation includes a configuration for JWT headers and payloads, a signing-key alias, and an access-token endpoint. The exact assertion claims depend on the receiving authorization server. In particular, verify the correct audience with the applicable current identity-domain documentation and configuration rather than copying a sample value blindly.
Milestone E — Map the originating Subject into the invoke
Start here: The same nonproduction project and integration, with its REST trigger and JWT-assertion REST invoke connection configured.
Navigation: Open the integration design and select the mapper between the trigger and invoke connections.
Steps
- Open the mapping action between the trigger and the REST invoke.
- Locate the source trigger's security Subject element.
- Locate the target invoke's security Subject element.
- Map the source trigger Subject directly to the target invoke Subject, as required by the documented Oracle identity-propagation pattern.
- Review the mapping to ensure the target Subject comes from the authenticated trigger's security property, not a similarly named business-payload element, model-visible parameter, request header that the caller can choose, or fixed username. Expand the mapper's actual security-property nodes rather than inventing an XPath from this article.
- Save the mapping and validate the integration using the normal project design workflow. Activate only the nonproduction version intended for this test.
Expected result: The source security Subject is connected to the invoke security Subject. This is the mapping Oracle identifies as necessary for sending the originating user to the endpoint system.
If this fails: Stop if the trigger Subject or invoke Subject is absent. Confirm that the selected trigger and invoke types and security policies support the intended mapping. Do not replace a missing security Subject with a normal payload field named userId.
Worked Example: The mapping must carry the caller, not a fixed test identity
Assume Employee A authenticates through the approved user flow and invokes the purchase-order tool. The trigger exposes the originating security Subject as Employee A's recognized principal. The mapper passes that Subject to the downstream invoke's Subject property.
The same integration is then invoked by Employee B. The business tool arguments can remain identical, but the trusted source Subject should reflect Employee B, and the mapper should carry that value through the supported downstream exchange.
A fixed Subject can make a test appear successful while every request acts as the same user. The decisive check is not what the mapper looks like in isolation; it is the actual effective principal seen by the target for each independently authenticated caller.
After configuring the mapping, register the integration as an agentic AI tool so the project MCP server can expose it. The registered tool is an interface to the integration; it is not a replacement for integration authentication or target authorization.
06
Configure the MCP Server and MCP Gateway
The identity-propagation pattern depends on two separate configured routes. The gateway uses an MCP server endpoint for routing and server authentication. The final client uses the gateway's runtime URL. Reversing these endpoints or substituting one token for another can lead to a misleading connection failure.
Prepare the integration as a tool first
For this project tool-registration path, Oracle requires an integration in a project, an active integration, and a first REST Adapter trigger connection with OAuth authentication and a JSON payload. Confirm those prerequisites before creating the tool. Name and Identifier are both immutable after creation; the identifier supplies model-facing metadata, while the display name is not the model-facing identity contract.
Milestone F — Register the existing integration as an MCP tool
Start here: The intended OIC project, with the integration active, the trigger configured, and the mapped REST invoke saved.
Navigation: Projects > select the project > Integrations section.
Steps
- Locate the active nonproduction integration that retrieves a purchase order for the authenticated caller.
- Open the integration's Actions menu and select Create agentic AI tool.
- Review the tool creation panel. Check the proposed Name, Identifier, and Description. Choose the identifier carefully because Oracle documentation says the identifier cannot be changed after creation.
- Select Create. The tool details page opens after creation.
- Review the tool description, guidelines, and input parameters on the details page. Ensure the tool exposes only the needed purchase-order identifier and does not expose an ordinary argument that lets the caller choose another user's identity.
- Select Save on the tool details page.
- Return to the project workspace and confirm the integration is registered as a tool.
Expected result: The tool registration exists, its identifier is known, and its permitted input parameters and description reflect the intended read-only action.
If this fails: Do not create another tool with a speculative name and continue. Check integration activation and registration status, then inspect the actual registered metadata before proceeding.
For the project MCP server to expose the registered integration, the project must have MCP enabled and the required runtime URL available. Oracle documents the project server connection using Streamable HTTP for supported MCP clients. Check the current client connection guide rather than assuming an ordinary REST POST creates a complete MCP session.
Milestone G — Add the project MCP server to the gateway configuration
Start here: The same nonproduction project, with MCP enabled and the project's MCP server runtime URL available. The REST invoke connection, Subject mapping, and tool registration must already be completed.
Navigation: Projects > select the project > left toolbar MCP Gateway > MCP servers section.
Steps
- In the MCP servers section, select Add.
- Enter a descriptive server name such as
Procurement Project MCP Serverand review the generated identifier and description. - Select Add. The MCP connection page appears.
- Enter the project MCP server's actual runtime URL in MCP Endpoint. Do not enter the final gateway URL here.
- Under Optional Properties, provide the required assertion claims using values accepted by the identity domain. The published identity-propagation example includes issuer, subject, audience, and signing-key information.
- Under Security, select OAuth using JWT User Assertion for the documented user-propagation pattern.
- Set Access Token URI to the correct authorization server's token endpoint.
- Set JWT Private Key Alias to the intended key alias uploaded to Oracle Integration and used in the relevant invoke configuration.
- Set the required Scope and any optional access-token request property supported by the current screen and security policy. Use the values provided by the target identity-domain design.
- Review the Issuer, Subject, Audience, and Signing Key ID values. Treat them as security configuration, not merely labels; confirm each value with the corresponding application and certificate setup.
- Select Test. Stop if the connection test fails and resolve the specific security or endpoint error.
- Select Save only after the required connection settings and test are satisfactory. Confirm that the registered tool is discovered in the server's configuration.
Expected result: The server connection has the intended endpoint and security policy, and its registered tool is discovered after the connection is tested and saved.
If this fails: Separate endpoint connectivity from authentication and tool discovery. Check the server URL, user-assertion configuration, audience, signing-key/certificate relationship, scopes, and registered tool status. Do not select No Security Policy to make a sensitive route connect.
The Subject shown in the gateway's MCP-server configuration must be understood in the context of the documented identity-propagation flow. Oracle's example has different usernames in design-time configuration, the JWT payload, and the runtime test, while the mapped originating runtime user is shown at the endpoint. Do not assume a configured design-time username is proof of which user will reach the target; verify the runtime result.
Create the gateway and assign the configured server
Milestone H — Create and configure the MCP gateway
Start here: The same project, with the server registered and its connection tested and saved.
Navigation: Projects > select the project > left toolbar MCP Gateway > MCP gateways section.
Steps
- In the MCP gateways section, select Add.
- Enter a descriptive gateway name such as
Procurement User Context Test. Review the generated identifier and description. - Select Create to open the gateway details page.
- In the MCP Servers section, select the configured procurement project MCP server.
- In the Policies section, select only the relevant policies for this nonproduction test. The identity propagation procedure itself does not require inventing additional gateway policies.
- Review the policy evaluation order if policies are attached, and select Save to save the gateway configuration.
- Confirm that the intended server is associated with the gateway and the configuration has been saved.
Expected result: The new gateway contains the selected configured MCP server. The gateway configuration is saved but runtime use is still gated by successful activation and the relevant client authorization.
If this fails: Check that the server is configured, the tool was discovered, and the gateway has been saved. Do not treat a saved gateway as an activated or authorized runtime endpoint.
At this point, there are two separate endpoint values to retain:
| Value | Used by | Purpose |
|---|---|---|
| Project MCP server runtime URL | The gateway's server registration | The downstream server endpoint to which the gateway routes the MCP request. |
| MCP gateway runtime URL | The final authorized MCP client | The governed endpoint that the host/client connects to and uses for discovery and invocation. |
Activate the gateway without confusing authorization modes
Milestone I — Activate the gateway for the chosen identity flow
Start here: The saved gateway in the same nonproduction project, with its selected server and any intended policies already assigned.
Navigation: Projects > select the project > left toolbar MCP Gateway > select the gateway > Actions.
Steps
- Open the gateway's Actions menu and select Activate. This opens the activation configuration flow.
- Select an appropriate tracing level. For an identity test that does not require payload capture, use the documented production-style trace setting. Do not enable request/response payload capture in a production-like environment merely to make debugging easier.
- Select the authorization mode deliberately. For the documented end-user identity-propagation example, follow the Authorization Code caller flow using a gateway authorization configuration that supports that flow; the public propagation page does not clearly identify its selected gateway activation mode in its text.
- The activation guide documents Use OIC integration authorization as sharing the service instance authorization model. Considering it for this user-context test is an architectural inference; the propagation use case does not explicitly confirm which activation mode it uses. Have the OIC/identity administrator confirm the supported mode, Authorization Code grant, resource scope, and user context in the intended instance before treating this as an executable end-to-end lab. Record that confirmed combination in the test evidence.
- Select the final Activate action to complete activation. Choosing tracing and authorization settings is not by itself the final activation action.
- Confirm the gateway reaches its active state before using its runtime endpoint.
Expected result: The gateway is active and its runtime details are available. This does not establish that the end-user grant, token audience, server connection, or target authorization is correct; those require separate checks.
If this fails: Stop before runtime testing. Review the activation state, selected authorization mode, actual granted scope/audience, and the type of client token required by the mode.
There is an important authorization boundary here. Oracle documents dedicated gateway authorization as using a gateway-specific resource server, audience, and discovery/invocation scopes; its activation guide specifies a client-credentials application for that mode. The published end-user identity-propagation use case instead describes a caller using an Authorization Code token.
The shared OIC integration authorization mode uses the service-instance audience and integration scope urn:opc:resource:consumer::all; obtain its complete granted value from the actual resource configuration. The dedicated mode uses its generated gateway resource and both full discovery/invocation scopes. Neither a scope suffix nor the word OAuth identifies the caller. Oracle documents deactivation and reactivation when changing an active gateway's authorization mode; treat such a change as an operational event.
Do not assume those instructions prove that every gateway authorization mode supports every user-propagation grant. If production policy requires dedicated gateway authorization, validate the current supported combination of gateway mode, caller grant, scope assignment, and user propagation before relying on it. Do not switch to client credentials and then claim the call represents an interactive employee unless the effective identity is established by the documented design and evidence.
Where dedicated gateway authorization is selected, the documented lifecycle is also distinct: activate the gateway and create its resource-server information, open the gateway's Actions menu and choose Run to view run details, obtain the generated resource-server name, add the actual generated discovery and invocation scopes to the appropriate confidential client application, submit the OAuth configuration, acquire a token with the required grant, and test the gateway endpoint. Never invent the resource-server audience or scope strings from a screenshot or another tenant.
Safety Check
Risk: A gateway is active and callable, but the client token uses the wrong identity context, audience, grant, or scope.
Control: Confirm the chosen authorization mode, token issuance grant, resource audience, required scopes, and runtime caller before testing user-level access.
Remaining risk: Gateway authorization can restrict entry without proving the target will distinguish one employee's permissions from another's.
07
Verify Propagation with Two Corporate Test Users
A successful connection test proves only that a particular connection could be established under its tested configuration. A successful tool invocation proves that one request completed. Neither by itself proves that user identity is preserved or that per-user permissions are enforced.
The practical outcome of this tutorial is a repeatable evidence set showing which identity reaches the target and whether different user permissions remain distinct.
Worked Example: Build a permission difference into the data
Assume the test backend contains two synthetic employees and two read-only purchase orders.
Employee A: may view PO-4101 and PO-4202.
Employee B: may view PO-4202, but is not allowed to view PO-4101.
This deliberate difference is critical. If both users have identical permissions, a pair of successful responses cannot prove per-user isolation.
Milestone J — Acquire separate caller tokens and test the gateway
Start here: An active nonproduction gateway, the correct runtime gateway URL, a supported MCP client, and two test users configured for the selected user-context authorization flow.
Navigation: Projects > select the project > MCP Gateway > select the active gateway > Actions > Run.
Steps
- Open the gateway's run details and record the actual gateway endpoint. Do not substitute the project MCP server URL.
- In the chosen supported MCP client, configure the documented authorization flow for the gateway. Obtain a token for Employee A through that employee's own authenticated user session. Do not reuse an application-only client-credentials token as evidence of Employee A's individual identity.
- Connect the client to the gateway runtime endpoint and discover the available tools. Record the actual identifier and input schema of the intended read-only purchase-order tool.
- Invoke the discovered tool with the valid arguments for
PO-4101. Use the tool's actual schema; the sample identifier and arguments in this article are illustrative. - Record the client result and the matching integration execution evidence. Locate the target's audit event for the same request and confirm the effective identity recorded there.
- Disconnect or replace the test user's authentication context using the supported client workflow. Authenticate as Employee B and obtain a new user-context token. Do not simply change a username field in an existing request.
- Repeat discovery and invoke the same actual tool with the same valid
PO-4101arguments. - Record the target authorization decision, the principal it observed, and whether the request returned any purchase-order data.
- As a positive cross-check, invoke the same tool as Employee B with
PO-4202, a record that Employee B is allowed to view. Record the target's effective user and authorization result again.
Expected result: Employee A can view PO-4101, Employee B is denied access to PO-4101 without receiving its data, and Employee B can view PO-4202. Target audit evidence identifies the correct effective user for each request.
If this fails: Stop if the correct tool cannot be discovered, the token represents the wrong principal, the target does not show its effective identity, or the denial occurs at an unrelated layer. Do not mark identity isolation as passed from a generic client error alone.
Use separate client profiles or a verified sign-out and reconnect procedure for the two users. A browser single-sign-on session, refresh token, cached MCP session, or connection pool can otherwise keep using the previous identity. Add an A → B → A sequence with the same purchase-order arguments and confirm the target principal on every call. Any response or token cache must preserve user isolation; these tests check behavior rather than assuming a particular OIC cache implementation.
Also test missing, expired, and wrong-audience credentials separately from a valid but record-unauthorized user. Use the target's independently verified permission baseline for each employee. If the backend intentionally returns “not found” for an unauthorized record, retain trusted target-side evidence of the access decision rather than expecting a universal HTTP status. Check that denied record data does not appear in the tool response, generated explanation, or permitted evidence views.
For a reproducible test, retain a sanitized correlation identifier for each request. Collect only the evidence needed to connect the client action, gateway activity, integration execution, identity-domain exchange, and target audit event. Use a correlation value already supported by the real tool or transport; do not invent an extra business argument that violates the schema. Do not collect private keys, access tokens, full JWTs, or unnecessary purchase-order payloads.
Acceptance matrix
| Test | Expected observation | Evidence to retain |
|---|---|---|
| Employee A reads PO-4101 | Request succeeds using Employee A's allowed permissions. | Caller identity, integration instance, target principal, target allow decision, and correlation value. |
| Employee B reads PO-4101 | Target denies the request and no protected purchase-order data is returned. | Target principal, denial decision, matching integration evidence, and absence of unintended data return. |
| Employee B reads PO-4202 | Request succeeds using Employee B's permitted access. | Target principal, allow decision, and matching request correlation. |
| Caller uses an invalid or wrong-audience token | The relevant authentication or authorization boundary rejects the invalid request. | Actual rejecting layer and sanitized error evidence. Do not infer which layer rejected from a generic status alone. |
Mark each row as passed, failed, or not executed based on observed evidence. An exercise carried out on paper or inferred from configuration is not a lab-verified result. A gateway-level denial is also not proof that the target enforced the intended per-user rule.
Safety Check
Risk: A test reports denial, but the cause is a malformed token or missing scope instead of the target's per-user authorization rule.
Control: Use valid tokens and arguments for the tested control, compare two different user contexts, and inspect the target's recorded principal and decision.
Remaining risk: Passing tests on two records does not prove that every record, action, integration, or authorization path is correctly isolated.
08
Common Mistakes and Targeted Troubleshooting
When identity propagation fails, locate the first failing layer before changing the configuration. A token-issuance problem, gateway rejection, server-connection error, failed Subject mapping, and target permission denial are different failures. Treat a status code or a client's error message as evidence to investigate, not as a complete diagnosis.
| Symptom | Targeted check | Minimal correction and retest |
|---|---|---|
| The authorization server refuses the assertion. | Check assertion issuer, subject, audience, timestamps, grant settings, signing algorithm, key identifier, public certificate, and client registration. | Correct the specific unsupported claim or trust mismatch, then repeat only the token-issuance test. |
| The token is issued but the gateway rejects the call. | Inspect the selected gateway authorization mode, actual token audience, requested scopes, token expiry, and gateway activation state. | Correct the gateway client configuration and test a permitted discovery/invocation operation. Do not change the REST invoke connection until the gateway call is valid. |
| The server connection test fails or the tool is not discovered. | Check the project server endpoint, security policy, authorization details, integration/tool registration, and project MCP configuration. | Resolve the server connection or discovery failure and re-test before attempting a business call. |
| Both employees appear as the same target principal. | Check the actual authenticated caller, runtime Subject, integration mapping, invoke security policy, and token obtained for the target. | Remove the fixed or incorrectly sourced identity, restore the trusted Subject mapping, and repeat both users' tests. |
| The target denies both users. | Check whether the target received a user-context token, whether the user exists in its identity model, and whether the required roles/scopes were granted. | Correct the target trust or user permission configuration and run the allowed-record test first. |
| One employee can read records assigned only to the other. | Inspect the effective principal, target authorization decision, integration logic, and any privileged service credentials that could bypass the target user's permissions. | Stop the test, disable the affected nonproduction exposure if needed, and fix the authorization boundary before retesting. |
Other mistakes to avoid
- Confusing an OAuth grant with a permission. A grant describes how a token is obtained. A role, scope, or application permission defines what that credential can be allowed to do.
- Treating tool guidelines as an authorization boundary. A natural-language tool description can help the model choose correctly. It cannot replace integration or target-system authorization.
- Forwarding an upstream bearer token to every downstream API. Each resource needs credentials and validation appropriate to its audience and security design. Blind token passthrough is a known OAuth/MCP risk.
- Confusing discovery with invocation permission. A tool's presence in a discovery list is not proof that it can be called successfully, nor that the user is authorized to access a particular business record.
- Testing only successful requests. User-isolation testing must include a valid but unauthorized record request and evidence that no protected data was returned.
If an error is ambiguous, collect the sanitized error, the failing component, the applicable release, the chosen authorization mode, and the relevant nonsecret configuration. Never share a bearer token, client secret, private signing key, or unredacted user/customer payload to troubleshoot the issue.
09
Enterprise Rollout: Ownership, Evidence, and Recovery
Identity propagation creates a chain of trust across the client, identity provider, gateway, server, integration, and target. No single configuration screen provides complete assurance for the entire chain. A production rollout should assign an owner and verification evidence to each relevant boundary.
| Responsibility | Suggested owner | Evidence to keep |
|---|---|---|
| Client application and user authentication | Identity/application team | Approved grant, authorized client configuration, user-context token test, and scope assignment record. |
| Signing material and certificate lifecycle | Security or certificate-management team | Key ownership, certificate identifiers, expiration and rotation schedule, trust configuration, and recovery procedure. |
| MCP tool registration and gateway policies | OIC platform team | Approved server endpoint, actual tool metadata, authorization mode, scopes, attached policy configuration, and activation evidence. |
| Subject mapping and integration runtime | Integration delivery team | Saved mapping, version and activation state, target connection configuration, and a successful two-user execution test. |
| Target authorization and audit | Business-system owner | User permissions, actual principal recorded, allow/deny decision, and absence of unintended data disclosure. |
Use tracing without creating unnecessary data exposure
Oracle's current gateway activation guide distinguishes a production-style tracing level that records activity without capturing request and response payloads from an audit-style level that includes payloads for troubleshooting. The guide lists retention of 32 days for production-style activity and eight days for audit activity that includes payloads. Confirm these settings against the current documentation and your tenancy before designing a retention policy.
Use a sanitized correlation value to match evidence across the client, gateway, integration runtime, and target audit log. Do not assume gateway traces will contain every field required to prove the target identity. Likewise, do not enable broad payload capture in production just because it makes a test easier to inspect.
Plan key rotation and rollback before production activation
- Record which applications and connections use each signing-key alias and public certificate.
- Before rotation, confirm how the new public certificate becomes trusted, how the OIC key alias is updated, and how old key material is retired without interrupting unrelated connections.
- Revalidate Subject mapping and two-user authorization whenever a security-policy change, key rotation, or relevant integration change could affect identity propagation.
- Define who can deactivate the gateway or revoke the client application during an incident, and how the previous known-good configuration is restored.
- Check the available promotion and deployment mechanisms for the actual OIC release instead of assuming that every identity application, key, endpoint, or authorization binding will move with a project export.
The direct project MCP endpoint also deserves attention during the threat review. A governed gateway does not, by itself, prove that every direct route to a backend has been disabled or restricted. Confirm the permissions and exposure of the project MCP server and underlying target separately. A lab's direct endpoint test must not become an approved production bypass.
Safety Check
Risk: A working two-user test is promoted without evidence of key rotation, production permissions, observability, rollback, or alternate access routes.
Control: Require owner-assigned evidence for the identity chain, target authorization, tracing, access restrictions, credential lifecycle, and recovery plan.
Remaining risk: Tests reduce uncertainty but cannot prove that every future configuration change, data record, or target permission remains correct.
Learning checkpoint
Using the fictional procurement example, answer these questions before treating the design as accepted:
- Which endpoint receives the employee's caller token, and which component issues a separate downstream token?
- Which integration mapping carries the originating Subject, and why is a normal tool parameter named
userIdinsufficient? - Which target audit evidence would distinguish Employee A from Employee B?
- What result would show that Employee B cannot read PO-4101 while still being allowed to read PO-4202?
The practical outcome is accepted only when the actual caller, mapped identity, target principal, and target decision agree with the expected test matrix. A configuration review alone leaves runtime identity propagation unverified.
10
❓ FAQ
Does selecting OAuth using JWT User Assertion automatically preserve the caller?
No. Identity propagation depends on the supported end-to-end configuration, including the originating Subject mapping, the relevant token exchange, and the target's authorization design.
What is the difference between the JWT header kid and the payload jti?
The header kid identifies a signing key, while the payload jti identifies a particular JWT. They serve different purposes and must not be substituted for each other.
Can client credentials prove which employee initiated a request?
Not by themselves. A client-credentials token normally represents an application or service identity; an employee identity needs a supported user-context design and evidence of the effective identity at the target.
Why is mapping the Subject in the integration important?
The mapping carries the trusted originating security Subject into the REST invoke's Subject property so the supported downstream identity flow can represent the caller instead of a fixed design-time user.
What proves that per-user authorization is working?
Run requests as two independently authenticated test users with different target permissions, then verify the target's effective principal, allow or deny decision, and returned-data behavior for each request.
11
🔗 References & Further Reading
The following primary sources were reviewed for the product boundaries, documented identity-propagation path, client prerequisites, and JWT semantics. Oracle product instructions must still be checked against the release and configuration actually available in your tenant.
- Oracle Integration: Use Case — Propagate User Identity for MCP Tool Invocations. The main reference for JWT user assertion, REST invoke Subject mapping, server configuration, and runtime propagation evidence.
- Oracle Integration REST Adapter: Authenticate Requests for Invoking Oracle Integration Flows. Reference for OAuth grants, JWT assertion setup, identity-domain client registration, signing certificates, and assertion claims.
- Oracle Integration REST Adapter: Upload a Certificate to Connect with External Services. Reference for the Certificates page, signing-key upload, aliases, and supported key formats.
- Oracle Integration MCP Gateway: Define MCP Servers to Manage. Reference for the managed-server connection page, MCP endpoint, security policy, and JWT user-assertion properties.
- Oracle Integration MCP Gateway: Create and Configure an MCP Gateway. Reference for gateway creation, server assignment, and policy configuration.
- Oracle Integration MCP Gateway: Activate an MCP Gateway. Reference for activation, tracing choices, authorization modes, and gateway-specific scope requirements.
- Oracle Integration: Register an Integration as an Agentic AI Tool. Reference for tool registration, metadata, parameters, and the creation workflow.
- Oracle Integration: Discover Integrations as Tools from MCP Clients. Reference for project MCP server prerequisites, runtime URL, and Streamable HTTP transport.
- Oracle Integration Release Notes: September 2026 (26.10). Reference for the release note identifying MCP Gateway and its minimum version.
- Oracle Integration: AI Feature Availability. Reference for regional availability statements and the need to check edition entitlement.
- IETF RFC 7519: JSON Web Token (JWT). Primary protocol reference for JWT claims, including issuer, subject, audience, time claims, JWT ID, and the distinction between payload claims and header parameters.
- IETF RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants. Reference for JWT-based OAuth client authentication and authorization grants.
- Model Context Protocol: Security Best Practices. Reference for protocol security risks such as inappropriate token passthrough and audience-validation failures. Protocol recommendations do not independently prove which mechanisms a particular Oracle release implements.
- Oracle REST Adapter — Prerequisites for Creating a Connection. Mandatory uploaded assertion claims and dynamically calculated time/identifier values.
- Oracle Integration — Get the URL for the MCP Gateway. Locating the client-facing endpoint under Actions and Run.
- IETF RFC 7515 — JSON Web Signature. The signed-header kid parameter and its key-identification role.
- Model Context Protocol — Tools. Tool name, description, and inputSchema shape. This reference does not establish the protocol revision supported by a particular OIC release.
12
📝 Summary
- Choose identity based on the business authorization requirement. A service account and an employee are different principals.
- Keep every token exchange and recipient distinct. The gateway's incoming token is not automatically the token used by the downstream target.
- Protect the JWT signing relationship. Validate the claims and certificate configuration, and distinguish the header's key identifier from the payload's JWT ID.
- Map the trusted originating Subject. The documented Oracle integration pattern maps the trigger Subject to the invoke Subject to propagate user identity.
- Prove the runtime result at the target. Test two independently authenticated users with deliberately different permissions and inspect the target's effective principal and authorization decision.
- Promote only after evidence and ownership are clear. Treat tracing, key rotation, scope management, alternate access paths, and rollback as part of the design.
The objective is not simply to make an MCP call succeed. It is to show that the employee who initiated the request remains correctly represented at the system that decides what that employee can see or do.
Continue building your Oracle Integration MCP Gateway knowledge by validating one security boundary at a time, retaining sanitized evidence, and treating untested assumptions as open engineering questions rather than completed controls.

Comments
Post a Comment