Reference: Authentication and Scopes

Authentication Model

DDFS relies on OCI Identity Domains to issue OAuth access tokens. Configure DDFS as a protected resource server, and configure a separate confidential client application for each independently managed caller. Grant each client only the resource and operation scopes required by its workflow.

For the complete setup procedure, see Create Integrated Applications for DDFS OAuth.

Identity Domain Applications

Where Scopes Are Configured and Requested

The same DDFS resource authority has a different form in each Identity Domains context:

Define a scope on the DDFS resource server before granting it to a client. A client can request only scopes that are granted to that client application. Token audience validation is independent of this scope mapping.

Scope Configuration Reference

Use the narrowest resource and operation scopes that satisfy the client workflow. The resource target must be supported by the selected DDFS FHIR version.

For the supported interactions and operations for each resource, see FHIR R4 Resources, FHIR R6 Resources, and FHIR Capability Statements. Check the deployed CapabilityStatement before configuring scopes for a client.

Scope Syntax

Define a FHIR resource scope on the DDFS resource server in this form:

system/<Resource>.<operations>

When granting or requesting that authority for a client, add the fixed ddfs prefix as described in Where Scopes Are Configured and Requested.

The resource name must identify a FHIR resource supported by the selected DDFS FHIR version. Use wildcard permissions only when a narrowly scoped alternative cannot satisfy the administrative workflow.

Resource Server Scope Definitions

Define every client-requestable DDFS scope on the resource server in canonical form. For example, system/Patient.r authorizes Patient read operations but not Patient search. Use system/Patient.rs or system/Patient.read when the client requires both read and search.

Confirm that the resource and interaction are advertised in the CapabilityStatement for the FHIR version used by the client.

Client Grants and Token Requests

Grant a client only the scopes required by that caller. Request the corresponding ddfs-prefixed values in the token request, separated by spaces.

For example, a client credentials token request for Device read and search access includes:

grant_type=client_credentials
scope=ddfssystem/Device.rs

Form-URL-encode the request body. After Identity Domains returns the access token, send it to DDFS in the Authorization: Bearer <access_token> header. Normal client operation does not require decoding the token.

Parameterized Scopes

A parameterized scope constrains resource authorization by appending supported FHIR search criteria after ?. Define the canonical form on the DDFS resource server and use the corresponding ddfs-prefixed form for the client grant and token request.

Resource server definition:

system/Device.rs?manufacturer=ExampleManufacturer

Client grant and token request:

ddfssystem/Device.rs?manufacturer=ExampleManufacturer

A coded-token constraint can include the system and code separated by |:

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

• Use only search parameters advertised for the target resource and FHIR version.
• Separate multiple requested scopes with a space.
• When one constrained scope contains multiple criteria, join the criteria with &.
• Form-URL-encode the complete token-request scope value. This protects spaces and reserved characters such as ?, &, and |.

Custom Hard-Delete Scope

The $hardDelete and $purgeDeleted operations require both a matching resource delete scope and the custom hard-delete scope.

Define these canonical values on the DDFS resource server for a Patient administration workflow:

system/Patient.d
https://docs.oracle.com/iaas/device-data-fhir/scopes/hard-delete

Grant and request these client-facing values:

ddfssystem/Patient.d ddfshttps://docs.oracle.com/iaas/device-data-fhir/scopes/hard-delete

The issued token contains the corresponding canonical values. Configure this elevated authorization only for administrative clients that require permanent-deletion operations.

Supported Authorization Boundary

DDFS uses OCI Identity Domains OAuth scopes for FHIR resource authorization. DDFS does not provide SMART launch workflows or authorize FHIR resources with SMART user/... and patient/... scope forms.

Use Access Tokens

Treat access tokens and client assertions as credentials. Do not log them, retain them longer than required, commit them to source control, or paste them into support tickets. Send an access token to DDFS only in the HTTP Authorization: Bearer <access_token> header.

Troubleshooting

For application-configuration problems, see Troubleshooting Integrated Application Setup.

FAQs

Why do resource-server and client scopes look different?

The resource server defines canonical system/... values. Client grants and token requests add the fixed ddfs prefix so Identity Domains can associate the request with the DDFS resource server.

Can I grant wildcard access?

Wildcard syntax is available, but least privilege is preferred. Grant resource-specific operations unless an administrative workflow cannot function with a narrower scope.

Why must the token-request scope be form-URL-encoded?

The scope field can contain spaces and reserved characters. Form-URL encoding preserves the exact scope values when the request is submitted.

Where do I configure certificate-based client authentication?

Follow Step 3: Create and Activate the Client Application. For DDFS, configure the Client Credentials grant with JWT client-assertion authentication, select Trusted Client, and import the client's public certificate. The matching private key remains with the calling application and signs each short-lived JWT client assertion.

Does DDFS support SMART on FHIR authorization?

No. Use the OCI Identity Domains OAuth model and DDFS system scopes documented on this page.

Why does hard delete require two scopes?

The resource delete scope grants delete authority for the selected resource, while the custom hard-delete scope grants access to permanent-deletion operations. Both are required.

Should a client decode or store its access token?

No. A normal client sends the token to DDFS as a Bearer credential and retains it only as long as required for the authorized workflow.

Related Topics

• Create Integrated Applications for DDFS OAuth
• Authentication and Authorization
• Reference: Purge Deleted, Hard Delete, and Subscription Status
• Security Best Practices