Create Integrated Applications for DDFS OAuth

• Before You Begin
• Step 1: Prepare the Identity Domain
• Step 2: Create and Activate the DDFS Resource Server
• Step 3: Create and Activate the Client Application
• Step 4: Collect the Token Request Values
• Step 5: Request an OAuth Access Token
• Step 6: Call the DDFS FHIR API

• Confirm that you have administrator access to the identity domain that you want to use for DDFS. To create a domain, see Creating an Identity Domain. To use an existing domain, see Getting an Identity Domain's Details.
• Identify the DDFS FHIR resources and operations that the client requires. Grant only the minimum required scopes.
• Before configuring the client application, obtain a public certificate and its matching private key by using your organization's approved certificate-management process. See Importing a Trusted Partner Certificate.
• Create a DDFS instance or get a DDFS instance details to obtain the version-specific FHIR API base URL for the DDFS instance that the client calls.

  For example:

  https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r4

  or

  https://<ddfs-instance-id>.ddfs.<region>.oci.oraclecloud.com/api/fhir/r6-ballot4

The setup uses two confidential applications:

For the complete scope syntax and context mapping, see Where Scopes Are Configured and Requested.

1. Open the navigation menu, and select Identity & Security. Under Identity, select Domains.
2. Select the identity domain that you want to use for DDFS.
3. On the Domain details page, on the top navigation scroll to the right and select Settings.
4. Under Domain settings - Locale select Edit domain settings.
5. Under Access signing certificate, turn on Configure client access, and then save the changes.
6. Return to the Domain details page, and select Integrated applications.

Identity Domains publishes the public signing keys at this endpoint:

https://<identity-domain>/admin/v1/SigningCert/jwk

DDFS retrieves these public signing keys automatically to validate access-token signatures. The root-certificate download, PEM-file creation, and federation-partner installation steps are not part of this DDFS setup.

1. On the Integrated applications page, select Add application.
2. Select Confidential Application, and select Launch workflow.
3. Enter a name and description that identify this application as the DDFS resource server, and Submit the application. Avoid entering confidential information.
4. On the application details page, select Actions and then Activate the resource server application.
5. Select OAuth configuration, and then Edit the OAuth configuration.
6. Under Resource server configuration select Configure this application as a resource server now.
7. Turn on the option to Allow token refresh.
8. In Primary audience, enter the exact lowercase value ddfs.
9. Turn on the option to Add Scopes.
10. Select Add to add a Scope for each operation needed by the calling application, enter only the canonical DDFS scopes needed by the calling applications. For example, add system/Device.rs for Device read and search access or add system/Device.* for access to all device operations. Or you can add system/*.* for access to all operations for all resources.

    To define specific access to supported resources, see Scope Configuration Reference for a list of resource names, operation letters, client scope forms, Subscription status requirements, and administrative scopes required for hard delete operations.

11. Optionally, enter a display name or description for each scope.
12. Select Add and then Submit to save the OAuth configuration.

1. Return to the Integrated applications page for the DDFS domain, select Add application.
2. Select Confidential Application, and select Launch workflow.
3. Enter a name and description that identify the application or service that calls DDFS, and select Submit to create the application. Create a separate client application for each independently managed caller.
4. On the application's details page, select OAuth configuration, and then select Edit OAuth configuration, to configure it as a client.
5. Under Client Configuration, select the option to Configure this application as a Client now and then Submit.
6. Under Authorization, select Client credentials as the OAuth grant type for this service to service workflow; it is not a username and password sign in flow.
7. Under Token issuance Policy turn on the option, to Add resources so that you can add the DDFS resource server as an authorized resource.
8. Select Add Scope, now you can see the scopes setup previously for the resource server, select the checkbox next to the scopes you want to add, and then select Add and then select Submit to save the OAuth configuration.

   Grant only the client-facing DDFS scopes required by this caller. For example, grant ddfssystem/Device.rs when the client reads and searches Device resources or to grant the client access to all device operations, select ddfssystem/Device.*

9. On the application details page, select the Actions menu and then select Activate. Confirm the client application displays an Active status.
10. Select Settings and then select Trusted partner certificates.
11. Under Security, select Trusted Partner Certificates.
12. Select Import certificate, and import the public certificate that corresponds to the client's protected private key.

The private key remains with the calling application and is not uploaded to Identity Domains. The application uses the private key to sign each short-lived JWT client assertion sent with an access-token request.

Collect the following values without placing credentials or private key material in source control, logs, support tickets, or documentation.

Request a token from the identity domain by using the client credentials grant and a freshly generated JWT client assertion. The SCOPE value must contain only scopes already granted to the client application.

Treat the returned access token as a credential. Do not log it, retain it longer than required, or paste it into a support ticket.

Send the access token in the HTTP Authorization header when calling a protected DDFS FHIR endpoint:

Authorization: Bearer <access_token>

For example, a client with Device read permission can retrieve a Device resource:

curl -sS "${FHIR_API_BASE_URL}/Device/${DEVICE_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/fhir+json"

Use the access token only with requests authorized by its granted scopes. Do not decode the token as part of the normal client workflow.

The active client application can request an OAuth access token for its granted DDFS scopes and use that token to call the corresponding protected FHIR endpoints.

For general API diagnostics, see Troubleshooting.

Why are two integrated applications required?

The resource server represents the protected DDFS FHIR API and defines available scopes. The client application represents one caller and receives only the scopes that caller requires.

When do I activate the applications?

Activate each application after saving its OAuth configuration. The resource server must be active before you grant its scopes to the client, and the client must be active before it requests a token.

Why does this procedure use a JWT client assertion?

A JWT client assertion lets the confidential client prove possession of its private key without sending that private key to Identity Domains. The assertion is still short-lived credential material and must not be logged or reused.

How are the identity-domain signing certificate, client authentication certificate, and Subscription secret different?

1. Identity-domain access-signing configuration: In Step 1, enable access to the identity domain's signing certificate. This allows DDFS to obtain the identity domain's public signing keys and validate issued access tokens. DDFS retrieves the keys automatically; you don't create or upload the client authentication key pair, download a root certificate, or install a certificate at a federation partner in this step.
2. Client authentication key pair: Obtain a public certificate and matching private key by using your organization's approved process. In Step 3, configure the confidential application as a client, select the Client Credentials grant and Trusted Client, and import the public certificate. The private key remains with the calling application and signs each short-lived JWT client assertion. Adding a Confidential Application describes the general Identity Domains workflow and its available options; Step 3 identifies the selections required for DDFS.
3. Subscription secret: The OCI Vault secret for R6 Subscription notification authorization is separate and optional. It is used only when an R6 REST-hook endpoint requires an outbound Authorization header and is unrelated to the access-token request made by the calling application.

Do I need to decode the access token?

No. After Identity Domains returns the token, send it to DDFS in the Authorization: Bearer <access_token> header. Decode tokens only as part of an approved diagnostic process, and never disclose a live token.

Does this configure SMART on FHIR authorization?

No. DDFS uses OAuth scopes issued by OCI Identity Domains and does not provide SMART launch or SMART user and patient authorization scopes.

Configure hard-delete authorization only for an administrative workflow that must call $hardDelete or $purgeDeleted. These operations require a matching resource delete scope and the custom hard-delete scope. For the exact resource-server and client values, see Custom Hard-Delete Scope.

• Reference: Authentication and Scopes
• Creating FHIR Resources
• Security Best Practices