FHIR-Native Authentication for Healthcare

POST /oauth2/auth

Initiates the OAuth 2.0 authorization flow.

GET /oauth2/auth
  ?response_type=code
  &client_id=example_client
  &redirect_uri=https://app.example.com/callback
  &scope=patient/*.read launch/patient
  &state=random_state_string
  &code_challenge=S256_code_challenge
  &code_challenge_method=S256
  &aud=https://fhir.example.com
  &patient=Patient/123

POST /oauth2/token

Exchanges an authorization code for access and ID tokens.

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=example_client
&code=auth_code_from_previous_step
&code_verifier=original_code_verifier
&redirect_uri=https://app.example.com/callback

POST /identity/registration

Registers a new user in the system.

POST /identity/registration
Content-Type: application/json

{
  "traits": {
    "email": "user@example.com",
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "fhir_id": "Patient/123"
  },
  "password": "secure_password"
}

POST /identity/sessions/login

Authenticates a user and creates a session.

POST /identity/sessions/login
Content-Type: application/json

{
  "password_identifier": "user@example.com",
  "password": "secure_password"
}

GET /fhir/context

Retrieves the FHIR context for the current session.

GET /fhir/context
Authorization: Bearer {access_token}

POST /fhir/context

Sets the FHIR context for the current session.

POST /fhir/context
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "patient": "Patient/123",
  "encounter": "Encounter/456",
  "practitioner": "Practitioner/789"
}

1. Install the SDK

// Using npm
npm install @nexus-auth/client

// Using yarn
yarn add @nexus-auth/client

2. Initialize the Client

import { NexusAuth } from '@nexus-auth/client';

const nexusAuth = new NexusAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://your-app.com/callback',
  scope: 'openid profile patient/*.read',
  audience: 'https://fhir-api.example.com'
});

3. Start Authentication Flow

// Redirect to Nexus login
nexusAuth.authorize({
  // Optional FHIR context parameters
  patient: 'Patient/123',
  encounter: 'Encounter/456'
});

4. Handle Callback

// In your callback route
async function handleCallback() {
  try {
    const authResult = await nexusAuth.handleRedirect();
    
    // Use the tokens
    const accessToken = authResult.accessToken;
    const idToken = authResult.idToken;
    
    // Store tokens securely
    // ...
    
    // Redirect to your app
    window.location.href = '/dashboard';
  } catch (error) {
    console.error('Authentication error:', error);
  }
}

Authentication Endpoints

• /oauth2/auth - OAuth 2.0 authorization endpoint
• /oauth2/token - OAuth 2.0 token endpoint
• /oauth2/userinfo - OpenID Connect userinfo endpoint
• /oauth2/revoke - Token revocation endpoint

User Management Endpoints

• /identity/registration - User registration endpoint
• /identity/sessions/login - User login endpoint
• /identity/sessions/logout - User logout endpoint
• /identity/recovery - Account recovery endpoint

FHIR Context Endpoints

• /fhir/context - FHIR context management endpoint
• /fhir/smart/launch - SMART on FHIR launch endpoint
• /fhir/smart/callback - SMART on FHIR callback endpoint

Epic Integration

Integrate Nexus with Epic EHR systems using the following steps:

1. Register Nexus as an application in Epic's App Orchard
2. Configure OAuth 2.0 client credentials
3. Set up SMART on FHIR launch context
4. Implement patient context synchronization
5. Configure single sign-on with Epic UserWeb

Cerner Integration

Integrate Nexus with Cerner Millennium systems using the following steps:

1. Register Nexus in Cerner's code Console
2. Configure OAuth 2.0 client credentials
3. Set up SMART on FHIR launch context
4. Implement patient context synchronization
5. Configure single sign-on with Cerner's authentication system

Multi-Factor Authentication

Implement MFA with Nexus using the following methods:

• SMS verification
• Email verification
• Authenticator apps (TOTP)
• Biometric authentication
• Hardware security keys (FIDO2/WebAuthn)

Break-Glass Protocol

Implement emergency access protocols with Nexus:

1. Configure emergency access roles and permissions
2. Set up emergency access request workflow
3. Implement approval and notification processes
4. Configure comprehensive audit logging
5. Set up automatic access expiration

Role-Based Access Control

Implement RBAC with Nexus using FHIR resources:

1. Define roles based on Practitioner.role resources
2. Map roles to permissions and scopes
3. Configure role hierarchies
4. Implement context-aware role assignment
5. Set up role-based UI customization

Delegation and Proxy Access

Implement delegation and proxy access with Nexus:

1. Configure delegation relationships using FHIR RelatedPerson resources
2. Set up consent management for delegation
3. Implement time-limited delegation
4. Configure granular permission delegation
5. Set up comprehensive audit logging for delegated access

SMART App Launch Framework

Implement the SMART App Launch Framework with Nexus:

1. Configure SMART on FHIR client registration
2. Implement EHR launch flow
3. Implement standalone launch flow
4. Handle patient context
5. Implement SMART scopes

SMART Backend Services

Implement SMART Backend Services with Nexus:

1. Configure client credentials flow
2. Implement JWT authentication
3. Configure system scopes
4. Implement token introspection
5. Set up audit logging

SMART App Example

// Initialize SMART on FHIR client
const smartClient = FHIR.client({
  serverUrl: 'https://fhir-api.example.com',
  tokenResponse: {
    access_token: 'access_token_from_nexus',
    patient: 'Patient/123'
  }
});

// Get patient information
smartClient.request('Patient/123').then(
  function(patient) {
    console.log('Patient name:', patient.name[0].given.join(' ') + ' ' + patient.name[0].family);
  }
);

Patient Resource

Nexus uses Patient resources for:

• Patient identity verification
• Patient portal authentication
• Patient context in clinical applications
• Patient-specific access control

Practitioner Resource

Nexus uses Practitioner resources for:

• Clinical user authentication
• Role-based access control
• Clinical context in applications
• Practitioner-specific permissions

RelatedPerson Resource

Nexus uses RelatedPerson resources for:

• Caregiver authentication
• Proxy access management
• Guardian relationships
• Delegated access control