Skip to main content

Client Registration

Client registration is the process of creating OAuth 2.0/OpenID Connect client applications in Haste Health. Clients represent applications that need to authenticate users or access resources on the FHIR server.

In Haste Health, client applications are managed as FHIR resources using the ClientApplication resource type. This allows clients to be created, updated, and managed through the standard FHIR API.

Overview​

A ClientApplication resource represents an OAuth 2.0 client and contains:

  • Client Identity: Unique identifier and human-readable name
  • OAuth Configuration: Grant types, response types, and redirect URIs
  • Security Credentials: Client secret for confidential clients
  • Scopes: Pre-approved scopes the client can request
  • Additional Metadata: Logo URI, description, and other client information

Client Types​

Confidential Clients​

Confidential clients can securely store credentials (client secret). They are typically:

  • Backend Services: Server-to-server applications
  • CLI Tools: Command-line tools running in secure environments

Confidential clients use grant types:

  • client_credentials - Machine-to-machine authentication

Public Clients​

Public clients cannot securely store credentials. They include:

  • Single Page Applications (SPAs): JavaScript applications in the browser
  • Mobile Apps: Native mobile applications
  • Desktop Applications: Native desktop applications

Public clients must use:

  • authorization_code with PKCE (Proof Key for Code Exchange)
  • refresh_token - Token refresh capability

ClientApplication Resource Structure​

For complete field definitions, see the ClientApplication resource documentation.

Registering a Client​

Method 1: Using the FHIR API​

Register a client by creating a ClientApplication resource through the FHIR API:

Create a ClientApplication using the Haste Health CLI:

haste-health api create ClientApplication --data '{"resourceType": "ClientApplication", "id": "backend-service", "name": "Backend Service", "grantType": ["client_credentials"], "responseTypes": "token", "secret": "my-super-secret", "scope": "openid system/*.*"}'

Method 2: Using the Admin App​

You can also register clients through the Haste Health Admin App:

  1. Open your project's console and pick ClientApplication from the sidebar's resource types. You can also type ClientApplication into the command bar, or pin the type so it stays at the top of the sidebar.
  2. Click New ClientApplication.
  3. Fill in the client details on the Form tab (or paste the whole resource on the JSON tab):
    • Client ID (must be unique)
    • Client Name
    • Grant Types
    • Redirect URIs (for authorization code flow)
    • Scopes
  4. Choose Actions → Create.

Client Configuration Examples​

patient/* scopes are not currently enforced

The Web Application and Mobile Application examples below request patient/* scopes to illustrate the intended shape for a patient-facing client. The server currently rejects any request whose best-matching scope is patient-level — request user/* scopes for a working client today.

A web application with user authentication:

{
  "resourceType": "ClientApplication",
  "id": "patient-portal",
  "name": "Patient Portal",
  "grantType": [
    "authorization_code",
    "refresh_token"
  ],
  "responseTypes": "token",
  "redirectUri": [
    "https://portal.example.com/callback"
  ],
  "scope": "openid profile email patient/*.read offline_access",
  "logoUri": "https://portal.example.com/logo.png"
}

Use Case: Patient-facing web portal for viewing health records Grant Flow: Authorization Code with PKCE → User Login → Consent → Tokens → API Access

Grant Types​

For grant types we support see the following documentation.

Scope Format​

openid profile email offline_access patient/*.read user/Patient.cruds

See Scopes documentation for complete scope syntax.

Access Control​

After registering a client, you may need to configure access policies to grant permissions.

Public clients requires user consent for requested scopes. The access policy used will be whatever policies are tied to the authenticated user.

Support​

For questions or issues with client registration:

  1. Review the ClientApplication resource documentation
  2. Check the OpenID Connect specification
  3. Consult the OAuth 2.0 specification
  4. Contact Haste Health support
  5. Open an issue on our GitHub repository