Create Integrated Applications for DDFS OAuth

Create an OCI Identity Domain integrated application that lets client applications request OAuth access tokens for Device Data FHIR Service (DDFS).

DDFS uses OCI Identity Domains for OAuth tokens with JWT validation. DDFS is not a SMART on FHIR authorization server and does not support SMART user/..., patient/..., or launch context scopes for FHIR resource authorization.

Tasks

Before You Begin
Review the Identity Domains OAuth Model
Step 1: Prepare the Identity Domain and Add the Confidential Application
Step 2: Configure the DDFS Resource Server
Step 3: Configure the Client Application
Optional Step: Configure Custom Hard-Delete Authorization
Step 4: Retrieve Credentials and Prepare Token Request Values
Step 5: Generate the OAuth Access Token

Before You Begin

Confirm that you have administrator access to the identity domain that you want to use for DDFS. To create a new identity domain, see Creating an Identity Domain or Getting an Identity Domain's Details to find an existing domain.
Identify the DDFS FHIR resources and operations the client or customer application needs. Grant only the minimum required scopes.
Review Reference: Authentication and Scopes before configuring scopes.

Identity Domains OAuth Model

Most server-to-server integrations use a confidential client application with client credentials or another approved confidential-client grant type. The exact grant type and client credential handling are deployment decisions owned by your identity administrator.

Use two integrated application concepts when configuring DDFS OAuth access. Scope syntax differs depending on whether the scope is defined on the DDFS resource server or granted and requested by a client application.

The audience and signing certificate settings allow DDFS to confirm that an access token is both intended for DDFS and was issued by the trusted identity domain. The identity domain puts ddfs, the configured primary audience, in the JWT aud claim, and DDFS rejects tokens whose aud claim does not contain this exact value. The identity domain JWKS contains the public signing keys that DDFS uses to verify the JWT signature. Enabling client access lets DDFS retrieve these keys from the identity domain.

Integrated Application	Purpose	Guidance	Scope Form	Example
Resource server application	Represents the protected DDFS FHIR API and defines the scopes clients may request.	Configure resource server behavior, set the primary audience to `ddfs`, and publish supported DDFS scopes.	Define FHIR resource scopes without the client-facing `ddfs` prefix.	`system/Device.rs`
Client application	Represents the system calling DDFS.	Configure OAuth client behavior, grant types, token issuance policy, and the DDFS resource scopes the client is allowed to request.	Grant and request FHIR resource scopes with the fixed client-facing `ddfs` prefix.	`ddfssystem/Device.rs`

Step 1: Prepare the Identity Domain and Add the Confidential Application

Open the navigation menu, and select Identity & Security. Under Identity, select Domains.
From the Domains list, select the identity domain you want to use for DDFS.
On the Domain details page, select Settings, and then select Edit domain settings. For the Oracle Console navigation, see Listing Domain Settings.
Under Access signing certificate, turn on the Configure client access toggle, and then select Save changes. When you turn this setting on, that enables DDFS to retrieve the identity domain's public signing keys from its JWKS to validate access-token signatures.
On the Domain details page, select the Integrated applications tab.
Select Add application.
Select Confidential Application, and select Launch workflow.
Enter the application Name and Description. Avoid entering confidential information.
Select Submit. The Confidential Application details page opens.

Step 2: Configure the DDFS Resource Server

Configure the application as the protected DDFS FHIR API resource server and define the DDFS scopes that client applications can request. Resource server scope definitions use the unprefixed system/... form.

Select the OAuth configuration tab, and select Edit OAuth configuration.
Select Configure this application as a resource server now.
Set Primary audience to ddfs. DDFS requires the access token's aud claim to contain this exact lowercase value.
Configure the access token expiration according to your deployment security standard.
Enable Add scopes.
Add only the DDFS FHIR resource scopes required by the client workflows. For example, add system/Patient.rs for Patient read and search, or system/Observation.read for Observation read and search.
If a client must call $hardDelete or $purgeDeleted, complete Optional Step: Configure Custom Hard-Delete Authorization after configuring the client application.
Select Submit.

Resource Server Reference

Use the following values when configuring the DDFS resource server application.

Configuration Item	Guidance
Application type	Confidential application configured as a resource server.
Primary audience	Enter `ddfs`. DDFS rejects access tokens whose `aud` claim does not contain this exact lowercase value.
Access token lifetime	Set according to the deployment security standard.
Resource scopes	Define DDFS `system/...` scopes without the client-facing `ddfs` prefix, and define the custom hard-delete scope in its exact canonical form.
Activation	The application must be activated before clients can request tokens using the configured scopes.

Resource Server Scope Examples

Scope	Purpose
`system/Patient.rs`	Read and search Patient resources.
`system/Observation.read`	Read and search Observation resources.
`system/Device.write`	Create, update, and delete Device resources.
`system/*.r`	Read all supported FHIR resource types.
`system/.`	All supported operations for all supported FHIR resource types.

FHIR Resource Scope Details

Use the scope forms shown in the Identity Domains OAuth Model table when defining resource server scopes or requesting client scopes.

Define FHIR resource scopes on the DDFS resource server in this form:

system/<Resource>.<operations>

The same resource authority appears in these three contexts:

Context	Scope form
Resource-server definition	`system/...`
Client grant/token request	`ddfssystem/...`
Issued token's `scope` claim	`system/...`

Client grants and token requests use the fixed ddfs-prefixed form:

ddfssystem/<Resource>.<operations>

OCI Identity Domains emits the corresponding unprefixed canonical scope in the access token. Therefore, a client requests ddfssystem/Patient.rs, and the issued token contains system/Patient.rs. Token audience validation is independent of this scope mapping.

For example, a client credentials token request can include these form values:

grant_type=client_credentials
scope=ddfssystem/Device.cruds

In a successful token response, the access_token value is a signed JWT. Its decoded payload contains the corresponding canonical scope without the ddfs prefix. This excerpt omits all other token claims:

{
  "scope": "system/Device.cruds"
}

The resource can be a concrete FHIR resource name, such as Patient, Observation, or Device. The resource can also be * for a wildcard grant.

Letter	Operation
`c`	create
`r`	read
`u`	update
`d`	delete
`s`	search

Alias	Expands To
`read`	`r` and `s`
`write`	`c`, `u`, and `d`
`*`	`c`, `r`, `u`, `d`, and `s`

Parameterized Scopes

DDFS supports constrained system/... scopes by appending FHIR-style search criteria after ?. Define the constrained scope without the client-facing ddfs prefix on the DDFS resource server.

For example, define this constrained scope on the DDFS resource server:

system/Device.rs?manufacturer=Demo

The client application grant and token request use the same scope with the fixed ddfs prefix:

ddfssystem/Device.rs?manufacturer=Demo

The issued token contains the corresponding canonical scope:

system/Device.rs?manufacturer=Demo

In this example, system/Device.rs grants Device read and search access, and the advertised Device manufacturer search parameter restricts that access to matching Device resources.

Other client grant and token-request examples include:

ddfssystem/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs

ddfssystem/Subscription.rs?owner=Organization/550e8400-e29b-41d4-a716-446655440000

The Subscription example is R6-only. For each example, the issued token contains the corresponding canonical system/... scope without the leading ddfs prefix.

Criteria after ? constrain resource operation authorization.
Multiple criteria joined by & are treated as one constraint group.
A token may contain multiple constrained grants for the same resource and operation; matching groups are evaluated as alternatives.
Unsupported or malformed constraint criteria fail closed during authorization.
Use only search parameters advertised for the target resource in the current DDFS CapabilityStatement. Recheck the applicable R4 or R6 CapabilityStatement before configuring constrained scopes.

Step 3: Configure the Client Application

Configure each application that calls DDFS as an OAuth client and grant access only to the DDFS resource server scopes required by that application.

Configure the deployment-approved grant type. Client credentials is the common model for service-to-service clients that can protect a client secret or private key.
In the client application OAuth configuration, add the DDFS resource server as an authorized resource.
Grant the client access only to the DDFS resource scopes required by the workflow.
Use the fixed ddfs-prefixed scope form in client grants and token requests. For example, clients request the resource server scope system/Patient.rs as ddfssystem/Patient.rs. The issued token contains the canonical system/Patient.rs scope.
Store and rotate client credentials according to the identity domain and application security standard.

Client Application Reference

For each client application that calls DDFS, document configuration values as deployment-specific placeholders.

Configuration Item	Guidance
Application type	Confidential application for server-side clients that can protect a client secret or private key.
Grant types	Use the deployment-approved grant type. Client credentials is the common model for service-to-service clients.
Authorized resources	Grant access to the DDFS resource server scopes required by the client. Resource server definitions use unprefixed scopes, but token requests use fixed `ddfs`-prefixed values such as `ddfssystem/Patient.rs`. Prefer least privilege.
Client credentials	Store and rotate according to the identity domain and application security standard.
Token request scopes	Request only the `ddfs`-prefixed scopes needed for the workflow being performed. For example, use `ddfssystem/Patient.rs` in a token request for Patient read and search access.

Optional Step: Configure Custom Hard-Delete Authorization

Use this step only for administrator workflows that must permanently remove resources with $hardDelete or $purgeDeleted. Hard-delete authorization requires both the custom hard-delete scope and a matching delete grant for the target FHIR resource.

On the DDFS resource server application, define the custom hard-delete scope in this exact canonical form:
```
https://docs.oracle.com/iaas/device-data-fhir/scopes/hard-delete
```
Confirm the resource server also defines the delete scope for each resource that the administrator workflow can permanently delete. For example, use system/Patient.d for Patient hard-delete access, or system/*.d only when the workflow requires delete access across all supported resources.
On the client application, grant both the client-facing custom hard-delete scope and the matching resource delete scope. For example, grant these values for Patient hard-delete access:
```
ddfssystem/Patient.d ddfshttps://docs.oracle.com/iaas/device-data-fhir/scopes/hard-delete
```
When requesting an access token, request the same client-facing scope values. The issued token contains the corresponding canonical values:
```
system/Patient.d https://docs.oracle.com/iaas/device-data-fhir/scopes/hard-delete
```
Use the resulting access token only with the administrative delete workflow that requires this elevated access.

Step 4: Retrieve Credentials and Prepare Token Request Values

Before requesting an access token, collect the identity domain, client application, and DDFS scope values for your environment. Protect credentials and key material by using your organization's approved secrets-management process.

Configure the scopes in Identity Domains first, and request only scopes granted to the client application.

Value	Where to Get It
`DOMAIN_URL`	Use the base URL for the identity domain that issues DDFS tokens, for example `https://idcs-xxxxxxxx.identity.oraclecloud.com`. Use the identity domain selected for the DDFS integrated applications.
`CLIENT_ID`	Use the client ID from the confidential client application details page.
`CLIENT_ASSERTION`	Generate a short-lived, signed JWT client assertion immediately before requesting the access token, using the confidential client's configured credential method and approved identity-domain tooling. Do not treat the assertion as a reusable client credential or commit it to source control.
`SCOPE`	Use the `ddfs`-prefixed FHIR resource scopes granted to the client application. For example, use `ddfssystem/Patient.rs` to request Patient read and search access. For custom hard-delete authorization, use the client-facing value `ddfshttps://docs.oracle.com/iaas/device-data-fhir/scopes/hard-delete`. Separate multiple scopes with a space.
`FHIR_API_BASE_URL`	Copy the R4 FHIR API base URL or R6 FHIR API base URL from the DDFS instance Developer Integration details. Use the URL for the FHIR version that the client application calls.

For example, a client that reads and searches Patient resources requests the ddfssystem/Patient.rs scope and sends authorized FHIR requests to https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/<fhir-version>.

Replace <fhir-version> with r4 for R4 requests or r6-ballot4 for R6 requests. You can copy the complete version-specific base URL from the DDFS instance Developer Integration details.

Generate a new client assertion shortly before each token request. Do not persist generated assertions in application configuration or source control.

Step 5: Generate the OAuth Access Token

Use the values from Step 4: Retrieve Credentials and Prepare Token Request Values to request an OAuth access token from the identity domain. This example uses the client credentials flow with a JWT client assertion. If your identity administrator configured a different confidential-client credential method, use the approved token request pattern for that method.

Both the curl and PowerShell examples expect CLIENT_ASSERTION to contain a freshly generated, short-lived assertion.

The SCOPE value must contain the ddfs-prefixed FHIR resource scopes granted to the client application. For example, request ddfssystem/Patient.rs for Patient read and search access. For custom hard-delete authorization, request ddfshttps://docs.oracle.com/iaas/device-data-fhir/scopes/hard-delete. Do not request SMART user/..., patient/..., or launch scopes because DDFS does not support SMART on FHIR authorization.

curl -sS -X POST "${DOMAIN_URL}/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=${CLIENT_ID}" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=${CLIENT_ASSERTION}" \
  --data-urlencode "scope=${SCOPE}"

$body = @{
  grant_type = "client_credentials"
  client_id = $CLIENT_ID
  client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
  client_assertion = $CLIENT_ASSERTION
  scope = $SCOPE
}

$response = Invoke-RestMethod -Method Post `
  -Uri "$DOMAIN_URL/oauth2/v1/token" `
  -ContentType "application/x-www-form-urlencoded;charset=UTF-8" `
  -Body $body

$response.access_token

Result

After the resource server and client configuration are saved and activated, OCI Identity Domains can issue access tokens that DDFS validates for FHIR API access.

Token Validation Expectations

An inbound access token must include:

sub_type set to client or user.
scope containing the canonical system/... DDFS FHIR resource scopes required for the requested operations.
iss matching the expected issuer.
tenant_iss matching the configured Identity Domain URL.
aud containing ddfs.

DDFS can accept user-subject tokens for current-actor and provenance resolution. DDFS does not support SMART on FHIR authorization and does not authorize FHIR resources with SMART user/..., patient/..., launch, or fhirUser scopes.

Unsupported Scope Forms

DDFS rejects SMART-style user and patient scope forms for FHIR resource authorization, including:

ddfsuser/<Resource>.<operations>
ddfspatient/<Resource>.<operations>

DDFS also does not consume SMART launch context scopes or claims for FHIR authorization. Do not configure launch, launch/patient, patient, or fhirUser as DDFS resource authorization scopes. Non-DDFS scopes such as openid or profile may be present in an identity token workflow, but they do not grant FHIR resource access in DDFS.

Next Steps

For scope examples, see Reference: Authentication and Scopes
Configure OAuth Scopes by FHIR Resource
Troubleshooting

Oracle Cloud Infrastructure Documentation