Reference: Authentication and Scopes

Authentication Model

DDFS relies on OCI Identity Domains to issue OAuth access tokens. Administrators model DDFS as a protected resource server application, define the DDFS FHIR resource scopes on that resource server, and authorize client applications to request only the scopes needed for their workflows.

DDFS does not expose SMART authorization, token, or SMART configuration endpoints. The supported authorization model uses OAuth 2.0 scopes issued by OCI Identity Domains. Clients request ddfssystem/... scopes, and DDFS authorizes FHIR requests from the corresponding canonical system/... scopes in the issued access token.

Identity Domain Applications

Most server-to-server integrations use a confidential client application with client credentials or another deployment-approved confidential-client grant type. Exact grant type, credential storage, and rotation policies are deployment decisions owned by the identity administrator.

Where Scopes Are Configured and Requested

DDFS OAuth scopes appear in several places. The same resource authority uses these forms:

Token validation checks the access token's aud claim independently of this scope mapping.

Common Scope Configuration Examples

Use these examples as starting points for common backend workflows. Replace {Resource} with the specific FHIR resource required by the integration and grant only the minimum required scopes.

Both scopes for the selected Subscription $status operation are required. A request without the required SubscriptionStatus scope is rejected. If the token includes the SubscriptionStatus scope but omits the matching Subscription scope, the operation can return HTTP 200 with an empty search-set Bundle instead of HTTP 403 because no Subscription results are authorized.

Resource Server Scope Definitions

Define DDFS resource server scopes without the ddfs client-facing prefix. Token validation checks the access token's aud claim independently of FHIR resource scopes.

Do not define SMART user/... or patient/... scopes for DDFS FHIR resource authorization. SMART on FHIR authorization is not supported by DDFS.

Client Application and Token Scope Claims

Client application grants and token requests use the fixed ddfs prefix. Issued access-token scope claims use the corresponding canonical system/... form. This scope mapping is independent of audience validation; DDFS separately requires the token's aud claim to contain the exact lowercase value ddfs.

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"
}

DDFS authorizes requests using the canonical system/... values in the issued token. Resource server and token-claim examples use canonical scopes; client configuration and token-request examples use the fixed ddfs-prefixed form.

Scope Syntax

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

system/<Resource>.<operations>

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

ddfssystem/<Resource>.<operations>

Issued access tokens contain the corresponding canonical form:

system/<Resource>.<operations>

Parameterized Scopes

DDFS supports constrained system/... scopes by appending FHIR-style search criteria after ?. Define constrained scopes without the ddfs prefix on the DDFS resource server. Client grants and token requests use the fixed ddfs-prefixed form; issued token claims use the corresponding canonical system/... form.

Resource server definition example:

system/Device.rs?manufacturer=Demo

Client grant and token-request examples:

ddfssystem/Device.rs?manufacturer=Demo
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. Identity Domains emits each scope in the issued token without the leading ddfs prefix.

• Criteria after ? constrain the resource operation authorization.
• Multiple criteria joined by & are treated as one constraint group.
• A token can 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.

Custom Hard-Delete Scope

Hard-delete and purge-deleted routes require both the canonical DDFS hard-delete scope and a matching delete grant for the affected resource. Define the custom scope on the DDFS resource server in this canonical form:

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

This custom scope is not enough by itself. Define a matching delete scope for the affected resource on the resource server, such as system/<Resource>.d or system/*.d.

Example client grant and token request for hard-deleting a Patient:

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

Corresponding issued-token scope claim:

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

Unsupported SMART Scope Forms

DDFS rejects these client or token scope forms for FHIR resource authorization:

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

DDFS does not consume SMART launch context scopes or claims for FHIR authorization. DDFS does not support launch, launch/patient, patient, or fhirUser as part of DDFS resource authorization.

Non-DDFS scopes such as openid or profile can be present in an identity token workflow, but they do not grant FHIR resource access in DDFS.

Token Validation Expectations

An inbound access token must include:

• sub_type, with a supported value of client or user.
• scope, containing supported DDFS FHIR authorization scope forms when FHIR access is required.
• iss, which must match the expected issuer.
• tenant_iss, which must match the configured Identity Domain URL.
• aud, which must contain the exact lowercase value ddfs.

User-subject tokens can be accepted 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.

Related Topics

• Authentication and Authorization
• Configure OAuth Scopes by FHIR Resource
• Create Integrated Applications for DDFS OAuth
• Reference: Purge Deleted, Hard Delete, and Subscription Status